@magic-markdown/cli 0.3.20 → 0.3.25

package/dist/index.js

@@ -270,13 +270,11 @@ var require_punycode = __commonJS({
 });
 
 // src/index.ts
-import { readFile as readFile8 } from "node:fs/promises";
 import { resolve as resolve6 } from "node:path";
 
 // ../core/src/types.ts
-var SIDECAR_SCHEMA_VERSION = 1;
+var WORKSPACE_SCHEMA_VERSION = 1;
 var MANIFEST_PATH = ".mdocs/manifest.json";
-var SIDECAR_DIR = ".mdocs/docs";
 var CHECKPOINT_DIR = ".mdocs/checkpoints";
 
 // ../core/src/errors.ts
@@ -302,6 +300,11 @@ function createId(prefix) {
 function createDocId() {
   return createId("doc");
 }
+var DOC_ID_SEPARATOR = "\0";
+function deterministicDocId(rootId, path) {
+  const digest = fnv1a(`${rootId}${DOC_ID_SEPARATOR}${path}`).toString(16).padStart(16, "0");
+  return `doc_${digest}`;
+}
 function contentHashForText(value) {
   return `text_${fnv1a(value).toString(16).padStart(16, "0")}`;
 }
@@ -334,10 +337,10 @@ function parseWikilinkBody(value) {
 
 // ../core/src/markdown.ts
 var POLLUTING_PATTERNS = [
-  { name: "CriticMarkup addition", pattern: /\{\+\+[\s\S]*?\+\+\}/ },
-  { name: "CriticMarkup deletion", pattern: /\{--[\s\S]*?--\}/ },
-  { name: "CriticMarkup substitution", pattern: /\{~~[\s\S]*?~~\}/ },
-  { name: "CriticMarkup comment", pattern: /\{>>[\s\S]*?<<\}/ },
+  { name: "inline review addition marker", pattern: /\{\+\+[\s\S]*?\+\+\}/ },
+  { name: "inline review deletion marker", pattern: /\{--[\s\S]*?--\}/ },
+  { name: "inline review substitution marker", pattern: /\{~~[\s\S]*?~~\}/ },
+  { name: "inline review comment marker", pattern: /\{>>[\s\S]*?<<\}/ },
   { name: "mdocs HTML marker", pattern: /<!--\s*mdocs:/i },
   { name: "mdocs suggestion marker", pattern: /<!--\s*\/?\s*mdocs-suggestion\b/i },
   { name: "mdocs directive", pattern: /:{1,3}(?:comment|suggestion|anchor)\b/i }
@@ -355,7 +358,7 @@ function assertCleanMarkdown(markdown) {
     throw new MdocsError(
       "validation_error",
       `Markdown contains collaboration markup: ${names}`,
-      "Keep Markdown clean; record comments and suggestions through the sidecar commands instead of inline markers."
+      "Keep Markdown clean; record comments and suggestions through the document authority instead of inline markers."
     );
   }
 }
@@ -368,10 +371,6 @@ function titleFromMarkdown(path, markdown) {
 function getLines(markdown) {
   return markdown.length === 0 ? [] : markdown.split(/\r?\n/);
 }
-function extractLineRange(markdown, range) {
-  const lines = getLines(markdown);
-  return lines.slice(range.startLine - 1, range.endLine).join("\n");
-}
 function assertLineRangeWithin(markdown, range) {
   if (!Number.isInteger(range.startLine) || !Number.isInteger(range.endLine) || range.startLine < 1 || range.endLine < range.startLine) {
     throw new MdocsError(
@@ -406,7 +405,7 @@ function replacementLinesForRange(replacement) {
 function extractMarkdownImages(markdown, documentPath) {
   const masked = maskCode(markdown);
   const referenceDefinitions = collectReferenceDefinitions(markdown, masked);
-  const lineStarts2 = getLineStarts(markdown);
+  const lineStarts = getLineStarts(markdown);
   const images = [];
   let index = 0;
   while (index < masked.length) {
@@ -424,7 +423,7 @@ function extractMarkdownImages(markdown, documentPath) {
     }
     const alt = markdown.slice(labelOpen + 1, labelClose);
     const afterLabel = labelClose + 1;
-    const position = positionAt(lineStarts2, start);
+    const position = positionAt(lineStarts, start);
     if (masked[afterLabel] === "(") {
       const destinationClose = findClosingParen(markdown, afterLabel + 1);
       if (destinationClose === -1) {
@@ -492,7 +491,7 @@ function extractMarkdownLinks(markdown) {
   const codeMasked = maskCode(markdown);
   const referenceDefinitions = collectReferenceDefinitions(markdown, codeMasked);
   const masked = maskReferenceDefinitions(markdown, codeMasked);
-  const lineStarts2 = getLineStarts(markdown);
+  const lineStarts = getLineStarts(markdown);
   const links = [];
   let index = 0;
   while (index < masked.length) {
@@ -509,7 +508,7 @@ function extractMarkdownLinks(markdown) {
     }
     const label = markdown.slice(start + 1, labelClose);
     const afterLabel = labelClose + 1;
-    const position = positionAt(lineStarts2, start);
+    const position = positionAt(lineStarts, start);
     if (masked[afterLabel] === "(") {
       const destinationClose = findClosingParen(markdown, afterLabel + 1);
       if (destinationClose === -1) {
@@ -565,7 +564,7 @@ function extractMarkdownLinks(markdown) {
     }
     index = labelClose + 1;
   }
-  extractWikilinks(markdown, masked, lineStarts2).forEach((link2) => links.push(link2));
+  extractWikilinks(markdown, masked, lineStarts).forEach((link2) => links.push(link2));
   return links.sort((left, right) => left.line - right.line || left.column - right.column);
 }
 function toImageReference(image2) {
@@ -592,7 +591,7 @@ function toLinkReference(link2) {
     syntax: link2.syntax
   };
 }
-function extractWikilinks(markdown, masked, lineStarts2) {
+function extractWikilinks(markdown, masked, lineStarts) {
   const links = [];
   let index = 0;
   while (index < masked.length) {
@@ -609,7 +608,7 @@ function extractWikilinks(markdown, masked, lineStarts2) {
     }
     const parsed = parseWikilinkBody(markdown.slice(start + 2, close2));
     if (parsed) {
-      const position = positionAt(lineStarts2, start);
+      const position = positionAt(lineStarts, start);
       links.push({
         label: parsed.label ?? parsed.target,
         target: parsed.target,
@@ -889,12 +888,12 @@ function getLineStarts(value) {
   }
   return starts;
 }
-function positionAt(lineStarts2, index) {
+function positionAt(lineStarts, index) {
   let low = 0;
-  let high = lineStarts2.length - 1;
+  let high = lineStarts.length - 1;
   while (low <= high) {
     const middle = Math.floor((low + high) / 2);
-    const start = lineStarts2[middle] ?? 0;
+    const start = lineStarts[middle] ?? 0;
     if (start <= index) {
       low = middle + 1;
     } else {
@@ -904,532 +903,9 @@ function positionAt(lineStarts2, index) {
   const lineIndex = Math.max(0, high);
   return {
     line: lineIndex + 1,
-    column: index - (lineStarts2[lineIndex] ?? 0) + 1
-  };
-}
-
-// ../core/src/anchors.ts
-function selectorFromRange(markdown, range) {
-  const lines = getLines(markdown);
-  const selected = lines.slice(range.startLine - 1, range.endLine).join("\n");
-  const prefix = lines.slice(Math.max(0, range.startLine - 4), range.startLine - 1).join("\n");
-  const suffix = lines.slice(range.endLine, range.endLine + 3).join("\n");
-  return { quote: selected, prefix, suffix };
-}
-function remapAnchor(markdown, anchor) {
-  const lines = getLines(markdown);
-  const quoteLines = anchor.selector.quote.split(/\r?\n/);
-  const candidates = findQuoteCandidates(lines, quoteLines);
-  const best = bestCandidate(lines, candidates, anchor.selector);
-  if (!best) {
-    return {
-      ...anchor,
-      status: "needs_review",
-      confidence: 0,
-      updatedAt: nowIso()
-    };
-  }
-  const confidence = scoreContext(lines, best.startLine, best.endLine, anchor.selector);
-  return {
-    ...anchor,
-    status: confidence >= 0.65 ? "mapped" : "needs_review",
-    confidence,
-    range: best,
-    updatedAt: nowIso()
-  };
-}
-function remapAnchors(markdown, anchors) {
-  return anchors.map((anchor) => remapAnchor(markdown, anchor));
-}
-function findQuoteCandidates(lines, quoteLines) {
-  if (quoteLines.length === 0) return [];
-  const ranges = [];
-  const quoteText = quoteLines.join("\n");
-  for (let index = 0; index <= lines.length - quoteLines.length; index += 1) {
-    const candidate = lines.slice(index, index + quoteLines.length);
-    if (candidate.join("\n") === quoteText) ranges.push({ startLine: index + 1, endLine: index + quoteLines.length });
-  }
-  return ranges;
-}
-function bestCandidate(lines, candidates, selector) {
-  if (candidates.length <= 1) return candidates[0];
-  const scored = candidates.map((range) => ({ range, score: scoreContext(lines, range.startLine, range.endLine, selector) })).sort((left, right) => right.score - left.score);
-  const best = scored[0];
-  if (!best) return void 0;
-  const tied = scored.filter((candidate) => candidate.score === best.score);
-  return tied.length === 1 ? best.range : void 0;
-}
-function scoreContext(lines, startLine, endLine, selector) {
-  let score = 0.7;
-  const expectedPrefix = contextPrefix(selector.prefix);
-  if (expectedPrefix) {
-    const actualPrefix = contextPrefix(lines.slice(Math.max(0, startLine - 4), startLine - 1).join("\n"));
-    if (expectedPrefix && actualPrefix.endsWith(expectedPrefix)) score += 0.15;
-  }
-  const expectedSuffix = contextSuffix(selector.suffix);
-  if (expectedSuffix) {
-    const actualSuffix = contextSuffix(lines.slice(endLine, endLine + 3).join("\n"));
-    if (expectedSuffix && actualSuffix.startsWith(expectedSuffix)) score += 0.15;
-  }
-  return Math.min(1, score);
-}
-function contextPrefix(value) {
-  return value?.split(/\r?\n/).filter(Boolean).slice(-3).join("\n") ?? "";
-}
-function contextSuffix(value) {
-  return value?.split(/\r?\n/).filter(Boolean).slice(0, 3).join("\n") ?? "";
-}
-
-// ../core/src/review-markdown.ts
-var START_MARKER = "<!--mdocs-suggestion";
-var END_MARKER = "<!--/mdocs-suggestion-->";
-function parseReviewMarkdown(reviewMarkdown) {
-  const segments = [];
-  const suggestions = [];
-  let cursor = 0;
-  let canonicalOffset = 0;
-  while (cursor < reviewMarkdown.length) {
-    const markerStart = reviewMarkdown.indexOf(START_MARKER, cursor);
-    if (markerStart === -1) {
-      appendTextSegment(reviewMarkdown, segments, cursor, reviewMarkdown.length, canonicalOffset);
-      break;
-    }
-    appendTextSegment(reviewMarkdown, segments, cursor, markerStart, canonicalOffset);
-    canonicalOffset += markerStart - cursor;
-    const startClose = reviewMarkdown.indexOf("-->", markerStart);
-    if (startClose === -1) throw invalidReviewMarkdown("Unclosed mdocs suggestion marker.");
-    const attrs2 = parseMarkerAttributes(reviewMarkdown.slice(markerStart + START_MARKER.length, startClose));
-    if (!attrs2.id) throw invalidReviewMarkdown("Suggestion marker is missing an id.");
-    if (attrs2.kind !== "insert" && attrs2.kind !== "delete" && attrs2.kind !== "replace") {
-      throw invalidReviewMarkdown(`Suggestion ${attrs2.id} has an invalid kind.`);
-    }
-    const bodyStart = startClose + 3;
-    const markerEnd = reviewMarkdown.indexOf(END_MARKER, bodyStart);
-    if (markerEnd === -1) throw invalidReviewMarkdown(`Suggestion ${attrs2.id} is missing its closing marker.`);
-    const body = reviewMarkdown.slice(bodyStart, markerEnd);
-    if (body.includes(START_MARKER)) throw invalidReviewMarkdown(`Suggestion ${attrs2.id} contains a nested suggestion.`);
-    const parsedBody = parseSuggestionBody(attrs2.kind, body, attrs2.id);
-    const token = {
-      id: attrs2.id,
-      kind: attrs2.kind,
-      form: parsedBody.before.includes("\n") || parsedBody.after.includes("\n") ? "block" : "inline",
-      author: actorFromAttributes(attrs2),
-      message: attrs2.message,
-      createdAt: attrs2.createdAt,
-      updatedAt: attrs2.updatedAt,
-      before: parsedBody.before,
-      after: parsedBody.after,
-      markerStart,
-      markerEnd: markerEnd + END_MARKER.length,
-      canonicalStart: canonicalOffset,
-      canonicalEnd: canonicalOffset + parsedBody.before.length,
-      raw: reviewMarkdown.slice(markerStart, markerEnd + END_MARKER.length)
-    };
-    segments.push({ type: "suggestion", token });
-    suggestions.push(token);
-    canonicalOffset += token.before.length;
-    cursor = token.markerEnd;
-  }
-  return {
-    reviewMarkdown,
-    canonicalMarkdown: canonicalFromSegments(segments, statusLookup(void 0)),
-    segments,
-    suggestions
-  };
-}
-function projectCanonicalMarkdown(reviewMarkdown, sidecarStatuses) {
-  return canonicalFromSegments(parseReviewMarkdown(reviewMarkdown).segments, statusLookup(sidecarStatuses));
-}
-function deriveSidecarFromReviewMarkdown(sidecar, reviewMarkdown, options) {
-  const parsed = parseReviewMarkdown(reviewMarkdown);
-  const now = options.now ?? (/* @__PURE__ */ new Date()).toISOString();
-  const existingSuggestions = new Map(sidecar.suggestions.map((suggestion) => [suggestion.id, suggestion]));
-  const existingAnchors = new Map(sidecar.anchors.map((anchor) => [anchor.id, anchor]));
-  const anchors = sidecar.anchors.filter((anchor) => anchor.kind !== "suggestion");
-  const suggestions = [];
-  const base = { contentHash: contentHashForText(parsed.canonicalMarkdown), ...options.baseHead ? { head: options.baseHead } : {} };
-  for (const token of parsed.suggestions) {
-    const existing = existingSuggestions.get(token.id);
-    const anchorId = existing?.anchorId ?? stableAnchorIdForSuggestion(token.id);
-    const range = lineRangeForCanonicalSpan(parsed.canonicalMarkdown, token.canonicalStart, token.canonicalEnd);
-    const selector = selectorForCanonicalSpan(parsed.canonicalMarkdown, token.canonicalStart, token.canonicalEnd);
-    const anchor = {
-      ...existingAnchors.get(anchorId) ?? {},
-      id: anchorId,
-      kind: "suggestion",
-      status: "mapped",
-      selector,
-      range,
-      confidence: 1,
-      updatedAt: now
-    };
-    const author = token.author ?? existing?.author ?? options.author;
-    const message = token.message ?? existing?.message ?? "Suggested edit";
-    const suggestion = {
-      ...existing ?? {},
-      id: token.id,
-      anchorId,
-      status: "open",
-      kind: token.kind,
-      author,
-      message,
-      patch: {
-        type: "replace_lines",
-        range,
-        before: token.before,
-        after: token.after
-      },
-      base: existing?.base ?? base,
-      diff: {
-        before: token.before,
-        after: token.after,
-        summary: diffSummary(token.before, token.after)
-      },
-      projectionStatus: "clean",
-      reviewRange: { start: token.markerStart, end: token.markerEnd },
-      createdAt: token.createdAt ?? existing?.createdAt ?? now,
-      updatedAt: token.updatedAt ?? now
-    };
-    anchors.push(anchor);
-    suggestions.push(suggestion);
-  }
-  return {
-    ...sidecar,
-    reviewMarkdown,
-    anchors,
-    suggestions,
-    updatedAt: now
-  };
-}
-function createSuggestionMarkup(reviewMarkdown, patch, metadata) {
-  const parsed = parseReviewMarkdown(reviewMarkdown);
-  assertNoDuplicateSuggestionId(parsed, metadata.suggestionId);
-  const [contentStart, contentEnd] = lineRangeOffsets(parsed.canonicalMarkdown, patch.range);
-  const selected = parsed.canonicalMarkdown.slice(contentStart, contentEnd);
-  if (selected !== patch.before) {
-    throw new MdocsError(
-      "conflict",
-      "Suggestion target does not match the review document projection.",
-      "Re-read the document and create the suggestion against the current canonical text."
-    );
-  }
-  const [canonicalStart, canonicalEnd] = lineRangeReplacementOffsets(parsed.canonicalMarkdown, patch.range);
-  if (selectionTouchesSuggestion(parsed.suggestions, canonicalStart, canonicalEnd)) {
-    throw new MdocsError(
-      "conflict",
-      "Suggestion overlaps an unresolved suggestion.",
-      "Accept or reject the existing suggestion before creating another edit over the same text."
-    );
-  }
-  const rawStart = rawOffsetForCanonicalOffset(parsed.segments, canonicalStart);
-  const rawEnd = rawOffsetForCanonicalOffset(parsed.segments, canonicalEnd);
-  const before = parsed.canonicalMarkdown.slice(canonicalStart, canonicalEnd);
-  const after = replacementTextForSpan(parsed.canonicalMarkdown, patch, canonicalStart, canonicalEnd);
-  const marker = formatSuggestionMarker(metadata, kindForText(before, after), before, after);
-  const nextReviewMarkdown = `${reviewMarkdown.slice(0, rawStart)}${marker}${reviewMarkdown.slice(rawEnd)}`;
-  const token = parseReviewMarkdown(nextReviewMarkdown).suggestions.find((candidate) => candidate.id === metadata.suggestionId);
-  if (!token) throw invalidReviewMarkdown(`Failed to create suggestion ${metadata.suggestionId}.`);
-  return { reviewMarkdown: nextReviewMarkdown, token };
-}
-function projectReviewMarkdown(canonicalMarkdown, suggestions) {
-  let reviewMarkdown = canonicalMarkdown;
-  const open = suggestions.filter((suggestion) => suggestion.status === "open" && suggestion.patch?.type === "replace_lines").slice().sort((left, right) => left.patch.range.startLine - right.patch.range.startLine);
-  for (const suggestion of open) {
-    try {
-      reviewMarkdown = createSuggestionMarkup(reviewMarkdown, suggestion.patch, {
-        suggestionId: suggestion.id,
-        author: suggestion.author,
-        message: suggestion.message,
-        createdAt: suggestion.createdAt,
-        updatedAt: suggestion.updatedAt
-      }).reviewMarkdown;
-    } catch {
-    }
-  }
-  return reviewMarkdown;
-}
-function resolveSuggestionMarkup(reviewMarkdown, suggestionId, resolution) {
-  const parsed = parseReviewMarkdown(reviewMarkdown);
-  const token = parsed.suggestions.find((candidate) => candidate.id === suggestionId);
-  if (!token) {
-    throw new MdocsError("not_found", `Unknown suggestion: ${suggestionId}`, "Refresh review state and try again.");
-  }
-  const resolved = resolutionText(token, resolution);
-  return `${reviewMarkdown.slice(0, token.markerStart)}${resolved}${reviewMarkdown.slice(token.markerEnd)}`;
-}
-function escapeReviewSuggestionText(value) {
-  return value.replaceAll("\\", "\\\\").replaceAll("{++", "\\{++").replaceAll("++}", "\\++}").replaceAll("{--", "\\{--").replaceAll("--}", "\\--}").replaceAll("{~~", "\\{~~").replaceAll("~>", "\\~>").replaceAll("~~}", "\\~~}");
-}
-function lineRangeForCanonicalSpan(markdown, start, end) {
-  assertCanonicalSpan(markdown, start, end);
-  return lineRangeForOffsets(markdown, start, end);
-}
-function selectorForCanonicalSpan(markdown, start, end) {
-  assertCanonicalSpan(markdown, start, end);
-  const context = 160;
-  const prefix = markdown.slice(Math.max(0, start - context), start);
-  const suffix = markdown.slice(end, Math.min(markdown.length, end + context));
-  return {
-    quote: markdown.slice(start, end),
-    ...prefix ? { prefix } : {},
-    ...suffix ? { suffix } : {}
-  };
-}
-function appendTextSegment(source, segments, start, end, canonicalStart) {
-  if (end <= start) return;
-  segments.push({
-    type: "text",
-    text: source.slice(start, end),
-    start,
-    end,
-    canonicalStart,
-    canonicalEnd: canonicalStart + (end - start)
-  });
-}
-function canonicalFromSegments(segments, statuses) {
-  return segments.map((segment) => {
-    if (segment.type === "text") return segment.text;
-    const status = statuses(segment.token.id);
-    if (status === "accepted") return acceptedText(segment.token);
-    return originalText(segment.token);
-  }).join("");
-}
-function parseMarkerAttributes(raw) {
-  const attrs2 = {};
-  const pattern = /\s+([a-zA-Z][\w:-]*)="([^"]*)"/g;
-  let match2;
-  while ((match2 = pattern.exec(raw)) !== null) {
-    const key = match2[1];
-    if (key === "id" || key === "kind" || key === "authorId" || key === "authorKind" || key === "authorName" || key === "authorEmail" || key === "message" || key === "createdAt" || key === "updatedAt") {
-      attrs2[key] = decodeAttribute(match2[2] ?? "");
-    }
-  }
-  return attrs2;
-}
-function actorFromAttributes(attrs2) {
-  if (!attrs2.authorId || !attrs2.authorName) return void 0;
-  const kind = attrs2.authorKind === "agent" || attrs2.authorKind === "system" || attrs2.authorKind === "human" ? attrs2.authorKind : "human";
-  return {
-    id: attrs2.authorId,
-    kind,
-    name: attrs2.authorName,
-    ...attrs2.authorEmail ? { email: attrs2.authorEmail } : {}
-  };
-}
-function parseSuggestionBody(kind, body, id) {
-  if (kind === "insert") {
-    return { before: "", after: parseWrappedBody(body, "{++", "++}", id) };
-  }
-  if (kind === "delete") {
-    return { before: parseWrappedBody(body, "{--", "--}", id), after: "" };
-  }
-  if (!body.startsWith("{~~") || !body.endsWith("~~}")) {
-    throw invalidReviewMarkdown(`Replacement suggestion ${id} has invalid CriticMarkup payload.`);
-  }
-  const inner = body.slice(3, -3);
-  const separator = findUnescaped2(inner, "~>");
-  if (separator === -1) throw invalidReviewMarkdown(`Replacement suggestion ${id} is missing a separator.`);
-  return {
-    before: unescapeReviewSuggestionText(inner.slice(0, separator)),
-    after: unescapeReviewSuggestionText(inner.slice(separator + 2))
-  };
-}
-function parseWrappedBody(body, open, close2, id) {
-  if (!body.startsWith(open) || !body.endsWith(close2) || isEscapedAt(body, body.length - close2.length)) {
-    throw invalidReviewMarkdown(`Suggestion ${id} has invalid CriticMarkup payload.`);
-  }
-  return unescapeReviewSuggestionText(body.slice(open.length, -close2.length));
-}
-function formatSuggestionMarker(metadata, kind, before, after) {
-  const attrs2 = [
-    ["id", metadata.suggestionId],
-    ["kind", kind]
-  ];
-  if (metadata.author) {
-    attrs2.push(["authorId", metadata.author.id]);
-    attrs2.push(["authorKind", metadata.author.kind]);
-    attrs2.push(["authorName", metadata.author.name]);
-    if (metadata.author.email) attrs2.push(["authorEmail", metadata.author.email]);
-  }
-  if (metadata.message) attrs2.push(["message", metadata.message]);
-  if (metadata.createdAt) attrs2.push(["createdAt", metadata.createdAt]);
-  if (metadata.updatedAt) attrs2.push(["updatedAt", metadata.updatedAt]);
-  const attrText = attrs2.map(([key, value]) => `${key}="${encodeAttribute(value)}"`).join(" ");
-  const body = kind === "insert" ? `{++${escapeReviewSuggestionText(after)}++}` : kind === "delete" ? `{--${escapeReviewSuggestionText(before)}--}` : `{~~${escapeReviewSuggestionText(before)}~>${escapeReviewSuggestionText(after)}~~}`;
-  return `${START_MARKER} ${attrText} -->${body}${END_MARKER}`;
-}
-function stableAnchorIdForSuggestion(suggestionId) {
-  return `anchor_${suggestionId.replace(/[^a-zA-Z0-9_:-]/g, "_")}`;
-}
-function diffSummary(before, after) {
-  if (!before && after) return "Inserted text";
-  if (before && !after) return "Deleted text";
-  return "Replaced text";
-}
-function unescapeReviewSuggestionText(value) {
-  let result = "";
-  for (let index = 0; index < value.length; index += 1) {
-    if (value[index] !== "\\") {
-      result += value[index];
-      continue;
-    }
-    const next = value[index + 1];
-    if (next === void 0) {
-      result += "\\";
-      continue;
-    }
-    result += next;
-    index += 1;
-  }
-  return result;
-}
-function findUnescaped2(value, needle, from = 0) {
-  let index = value.indexOf(needle, from);
-  while (index !== -1) {
-    if (!isEscapedAt(value, index)) return index;
-    index = value.indexOf(needle, index + needle.length);
-  }
-  return -1;
-}
-function isEscapedAt(value, index) {
-  let slashes = 0;
-  for (let cursor = index - 1; cursor >= 0 && value[cursor] === "\\"; cursor -= 1) slashes += 1;
-  return slashes % 2 === 1;
-}
-function statusLookup(statuses) {
-  if (!statuses) return () => "open";
-  if (isStatusMap(statuses)) return (suggestionId) => statuses.get(suggestionId) ?? "open";
-  if (Array.isArray(statuses)) {
-    const map = /* @__PURE__ */ new Map();
-    for (const item of statuses) {
-      const id = item.id ?? item.suggestionId;
-      if (id && item.status) map.set(id, item.status);
-    }
-    return (suggestionId) => map.get(suggestionId) ?? "open";
-  }
-  const record = statuses;
-  return (suggestionId) => record[suggestionId] ?? "open";
-}
-function isStatusMap(value) {
-  return typeof value.get === "function";
-}
-function acceptedText(token) {
-  return token.kind === "delete" ? "" : token.after;
-}
-function originalText(token) {
-  return token.kind === "insert" ? "" : token.before;
-}
-function resolutionText(token, resolution) {
-  return resolution === "accept" ? acceptedText(token) : originalText(token);
-}
-function kindForText(before, after) {
-  if (before.length === 0) return "insert";
-  if (after.length === 0) return "delete";
-  return "replace";
-}
-function assertNoDuplicateSuggestionId(parsed, suggestionId) {
-  if (parsed.suggestions.some((suggestion) => suggestion.id === suggestionId)) {
-    throw new MdocsError("validation_error", `Duplicate suggestion id: ${suggestionId}`, "Suggestion ids must be stable and unique per document.");
-  }
-}
-function assertCanonicalSpan(markdown, start, end) {
-  if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end < start || end > markdown.length) {
-    throw new MdocsError("invalid_range", `Invalid canonical span ${start}:${end}.`, "Re-read the document and try again.");
-  }
-}
-function selectionTouchesSuggestion(tokens, start, end) {
-  return tokens.some((token) => {
-    if (token.canonicalStart === token.canonicalEnd) return start <= token.canonicalStart && end >= token.canonicalEnd;
-    return start < token.canonicalEnd && end > token.canonicalStart;
-  });
-}
-function rawOffsetForCanonicalOffset(segments, offset) {
-  for (const segment of segments) {
-    if (segment.type === "text") {
-      if (offset >= segment.canonicalStart && offset <= segment.canonicalEnd) {
-        return segment.start + (offset - segment.canonicalStart);
-      }
-      continue;
-    }
-    const token = segment.token;
-    if (offset > token.canonicalStart && offset < token.canonicalEnd) {
-      throw new MdocsError(
-        "conflict",
-        "Selection falls inside an unresolved suggestion.",
-        "Accept or reject the existing suggestion before editing inside it."
-      );
-    }
-  }
-  if (offset === segmentsEndCanonicalOffset(segments)) return segmentsEndRawOffset(segments);
-  throw new MdocsError("invalid_range", "Could not map canonical offset into review Markdown.", "Re-read the document and try again.");
-}
-function segmentsEndCanonicalOffset(segments) {
-  const last = segments[segments.length - 1];
-  if (!last) return 0;
-  return last.type === "text" ? last.canonicalEnd : last.token.canonicalEnd;
-}
-function segmentsEndRawOffset(segments) {
-  const last = segments[segments.length - 1];
-  if (!last) return 0;
-  return last.type === "text" ? last.end : last.token.markerEnd;
-}
-function lineRangeOffsets(markdown, range) {
-  const lines = getLines(markdown);
-  if (range.startLine < 1 || range.endLine < range.startLine || range.endLine > lines.length) {
-    throw new MdocsError("invalid_range", `Invalid line range ${range.startLine}:${range.endLine}.`, "Re-read the document and try again.");
-  }
-  let start = 0;
-  for (let index = 0; index < range.startLine - 1; index += 1) start += lines[index].length + 1;
-  let end = start;
-  for (let index = range.startLine - 1; index < range.endLine; index += 1) {
-    if (index > range.startLine - 1) end += 1;
-    end += lines[index].length;
-  }
-  return [start, end];
-}
-function lineRangeReplacementOffsets(markdown, range) {
-  const [start, contentEnd] = lineRangeOffsets(markdown, range);
-  if (contentEnd < markdown.length && markdown[contentEnd] === "\n") return [start, contentEnd + 1];
-  return [start, contentEnd];
-}
-function replacementTextForSpan(markdown, patch, start, end) {
-  const applied = replaceLineRange(markdown, patch.range, patch.after);
-  const suffixLength = markdown.length - end;
-  const replacementEnd = applied.length - suffixLength;
-  if (replacementEnd < start) return "";
-  return applied.slice(start, replacementEnd);
-}
-function lineRangeForOffsets(markdown, start, end) {
-  const starts = lineStarts(markdown);
-  return {
-    startLine: lineNumberAt(starts, start),
-    endLine: lineNumberAt(starts, Math.max(start, end - 1))
+    column: index - (lineStarts[lineIndex] ?? 0) + 1
   };
 }
-function lineStarts(markdown) {
-  const starts = [0];
-  for (let index = 0; index < markdown.length; index += 1) {
-    if (markdown[index] === "\n") starts.push(index + 1);
-  }
-  return starts;
-}
-function lineNumberAt(starts, offset) {
-  let line = 1;
-  for (let index = 0; index < starts.length; index += 1) {
-    if (starts[index] <= offset) line = index + 1;
-    else break;
-  }
-  return line;
-}
-function encodeAttribute(value) {
-  return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
-}
-function decodeAttribute(value) {
-  return value.replaceAll("&quot;", '"').replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&amp;", "&");
-}
-function invalidReviewMarkdown(message) {
-  return new MdocsError("validation_error", `Invalid review Markdown: ${message}`, "Repair or remove the malformed suggestion markup.");
-}
 
 // ../core/src/graph.ts
 function resolveMarkdownLinks(links, currentDocument, documents) {
@@ -1609,23 +1085,16 @@ function safeDecode(value) {
   }
 }
 
-// ../core/src/sidecar.ts
-function defaultActor(name = "mdocs") {
-  return {
-    id: "actor_local",
-    kind: "human",
-    name
-  };
-}
+// ../core/src/workspace-store.ts
+var cacheLookupSignatures = /* @__PURE__ */ new WeakMap();
 async function initWorkspace(io, workspaceId = createId("workspace")) {
   await io.mkdir(".mdocs");
-  await io.mkdir(SIDECAR_DIR);
   await io.mkdir(CHECKPOINT_DIR);
   const existing = await readManifestIfPresent(io);
   if (existing) return existing;
   const now = nowIso();
   const manifest = {
-    schemaVersion: SIDECAR_SCHEMA_VERSION,
+    schemaVersion: WORKSPACE_SCHEMA_VERSION,
     workspaceId,
     createdAt: now,
     updatedAt: now,
@@ -1634,315 +1103,169 @@ async function initWorkspace(io, workspaceId = createId("workspace")) {
   await writeManifest(io, manifest);
   return manifest;
 }
-async function indexWorkspace(io) {
-  const manifest = await initWorkspace(io);
-  const markdownFiles = await io.listMarkdownFiles();
-  const existingByPath = new Map(manifest.docs.map((doc) => [doc.path, doc]));
-  const markdownFileSet = new Set(markdownFiles);
-  const unmatchedExisting = manifest.docs.filter((doc) => !markdownFileSet.has(doc.path));
-  const claimedRenamedDocIds = /* @__PURE__ */ new Set();
-  const now = nowIso();
-  const docs = [];
-  const markdownByPath = /* @__PURE__ */ new Map();
-  const newPathCountByHash = /* @__PURE__ */ new Map();
-  for (const path of markdownFiles) {
-    const markdown = await io.readText(path);
-    assertCleanMarkdown(markdown);
-    const contentHash = contentHashForText(markdown);
-    markdownByPath.set(path, { contentHash, markdown });
-    newPathCountByHash.set(contentHash, (newPathCountByHash.get(contentHash) ?? 0) + 1);
-  }
-  for (const path of markdownFiles) {
-    const { contentHash, markdown } = markdownByPath.get(path);
-    const existing = existingByPath.get(path) ?? await findRenamedDocumentEntry(
-      io,
-      unmatchedExisting.filter((doc) => !claimedRenamedDocIds.has(doc.docId)),
-      markdown,
-      contentHash,
-      newPathCountByHash.get(contentHash) ?? 0
-    );
-    if (existing && existing.path !== path) claimedRenamedDocIds.add(existing.docId);
-    const docId = existing?.docId ?? createDocId();
-    const title = titleFromMarkdown(path, markdown);
-    const entry = {
-      docId,
-      path,
-      title,
-      contentHash,
-      currentSha: existing?.currentSha,
-      updatedAt: now
-    };
-    docs.push(entry);
-    await ensureDocumentSidecar(io, entry, markdown);
-  }
-  const next = {
-    ...manifest,
-    docs,
-    updatedAt: now
-  };
-  await writeManifest(io, next);
-  return next;
+async function indexWorkspace(io, options) {
+  return (await computeWorkspaceIndex(io, options)).manifest;
 }
-async function getWorkspaceMap(io) {
-  const manifest = await indexWorkspace(io);
-  const graph = await workspaceGraphForManifest(io, manifest);
+async function getWorkspaceMap(io, options) {
+  const { manifest, graphDocuments } = await computeWorkspaceIndex(io, options);
+  const graph = buildWorkspaceGraph(manifest.workspaceId, manifest.schemaVersion, graphDocuments);
   const graphNodesByDocId = new Map(graph.nodes.map((node) => [node.docId, node]));
-  const docs = await Promise.all(
-    manifest.docs.map(async (entry) => {
-      const sidecar = await readSidecar(io, entry.docId);
+  return {
+    workspaceId: manifest.workspaceId,
+    schemaVersion: manifest.schemaVersion,
+    docs: manifest.docs.map((entry) => {
       const graphNode = graphNodesByDocId.get(entry.docId);
       return {
         docId: entry.docId,
         path: entry.path,
         title: entry.title,
-        sidecarPath: sidecarPath(entry.docId),
-        openComments: sidecar.comments.filter((comment2) => comment2.status === "open").length,
-        openSuggestions: sidecar.suggestions.filter((suggestion) => suggestion.status === "open").length,
-        anchorsNeedingReview: sidecar.anchors.filter((anchor) => anchor.status !== "mapped").length,
+        openComments: 0,
+        openSuggestions: 0,
+        anchorsNeedingReview: 0,
         outgoingLinks: graphNode?.outgoingLinks ?? 0,
         incomingLinks: graphNode?.incomingLinks ?? 0,
         unresolvedLinks: graphNode?.unresolvedLinks ?? 0,
         externalLinks: graphNode?.externalLinks ?? 0
       };
     })
-  );
-  return {
-    workspaceId: manifest.workspaceId,
-    schemaVersion: manifest.schemaVersion,
-    docs
   };
 }
-async function getWorkspaceGraph(io) {
-  return workspaceGraphForManifest(io, await indexWorkspace(io));
+async function getWorkspaceGraph(io, options) {
+  const { manifest, graphDocuments } = await computeWorkspaceIndex(io, options);
+  return buildWorkspaceGraph(manifest.workspaceId, manifest.schemaVersion, graphDocuments);
 }
-async function getDocumentState(io, pathOrDocId) {
-  const manifest = await indexWorkspace(io);
+async function getDocumentState(io, pathOrDocId, options) {
+  const { manifest, graphDocuments, markdownByPath } = await computeWorkspaceIndex(io, options);
   const entry = findDoc(manifest, pathOrDocId);
-  const markdown = await io.readText(entry.path);
+  const markdown = markdownByPath.get(entry.path) ?? await io.readText(entry.path);
   assertCleanMarkdown(markdown);
-  const sidecar = await readSidecar(io, entry.docId);
-  const remappedAnchors = remapAnchors(markdown, sidecar.anchors);
-  const nextSidecar = {
-    ...sidecar,
-    anchors: remappedAnchors,
-    updatedAt: nowIso()
-  };
-  await writeSidecar(io, nextSidecar);
+  const source = graphDocuments.find((document) => document.docId === entry.docId);
+  const links = source?.links ?? resolveMarkdownLinks(extractMarkdownLinks(markdown), entry, manifest.docs);
   return {
     docId: entry.docId,
     path: entry.path,
     title: entry.title,
     markdown,
-    reviewMarkdown: nextSidecar.reviewMarkdown ?? markdown,
-    sidecar: nextSidecar,
-    anchors: remappedAnchors.map((anchor) => ({
-      id: anchor.id,
-      kind: anchor.kind,
-      status: anchor.status,
-      range: anchor.range,
-      quote: anchor.selector.quote,
-      confidence: anchor.confidence
-    })),
     images: extractMarkdownImages(markdown, entry.path),
-    links: resolveMarkdownLinks(extractMarkdownLinks(markdown), entry, manifest.docs),
-    openComments: nextSidecar.comments.filter((comment2) => comment2.status === "open").length,
-    openSuggestions: nextSidecar.suggestions.filter((suggestion) => suggestion.status === "open").length
-  };
-}
-async function workspaceGraphForManifest(io, manifest) {
-  const documents = await Promise.all(
-    manifest.docs.map(async (entry) => {
-      const [markdown, sidecar] = await Promise.all([io.readText(entry.path), readSidecar(io, entry.docId)]);
-      const links = resolveMarkdownLinks(extractMarkdownLinks(markdown), entry, manifest.docs);
-      return {
-        docId: entry.docId,
-        path: entry.path,
-        title: entry.title,
-        openComments: sidecar.comments.filter((comment2) => comment2.status === "open").length,
-        openSuggestions: sidecar.suggestions.filter((suggestion) => suggestion.status === "open").length,
-        anchorsNeedingReview: sidecar.anchors.filter((anchor) => anchor.status !== "mapped").length,
-        externalLinks: links.filter((link2) => link2.status === "external").length,
-        unresolvedLinks: links.filter((link2) => link2.status === "unresolved" || link2.status === "ambiguous").length,
-        links
-      };
-    })
-  );
-  return buildWorkspaceGraph(manifest.workspaceId, manifest.schemaVersion, documents);
-}
-async function addComment(io, pathOrDocId, range, body, author = defaultActor()) {
-  const state = await getDocumentState(io, pathOrDocId);
-  assertLineRangeWithin(state.markdown, range);
-  const now = nowIso();
-  const anchor = {
-    id: createId("anchor"),
-    kind: "comment",
-    status: "mapped",
-    selector: selectorFromRange(state.markdown, range),
-    range,
-    confidence: 1,
-    updatedAt: now
-  };
-  const comment2 = {
-    id: createId("comment"),
-    anchorId: anchor.id,
-    status: "open",
-    author,
-    body,
-    replies: [],
-    createdAt: now,
-    updatedAt: now
+    links,
+    openComments: 0,
+    openSuggestions: 0,
+    anchorsNeedingReview: 0
   };
-  await writeSidecar(io, {
-    ...state.sidecar,
-    anchors: [...state.sidecar.anchors, anchor],
-    comments: [...state.sidecar.comments, comment2],
-    updatedAt: now
-  });
-  return comment2;
 }
-async function addSuggestion(io, pathOrDocId, range, replacement, message, author = { id: "agent_local", kind: "agent", name: "Local Agent" }, changeSetId) {
-  const state = await getDocumentState(io, pathOrDocId);
-  const manifest = await indexWorkspace(io);
-  const entry = manifest.docs.find((doc) => doc.docId === state.docId);
-  assertLineRangeWithin(state.markdown, range);
-  assertCleanMarkdown(replacement);
+async function computeWorkspaceIndex(io, options) {
+  const baseline = await initWorkspace(io);
+  const cache = options?.cache;
+  const markdownFiles = await io.listMarkdownFiles();
+  const existingByPath = new Map(baseline.docs.map((doc) => [doc.path, doc]));
   const now = nowIso();
-  const before = extractLineRange(state.markdown, range);
-  const anchor = {
-    id: createId("anchor"),
-    kind: "suggestion",
-    status: "mapped",
-    selector: selectorFromRange(state.markdown, range),
-    range,
-    confidence: 1,
-    updatedAt: now
-  };
-  const suggestion = {
-    id: createId("suggestion"),
-    anchorId: anchor.id,
-    status: "open",
-    kind: replacement.length === 0 ? "delete" : before.length === 0 ? "insert" : "replace",
-    author,
-    message,
-    patch: {
-      type: "replace_lines",
-      range,
-      before,
-      after: replacement
-    },
-    base: {
-      contentHash: contentHashForText(state.markdown),
-      ...entry?.currentSha ? { head: entry.currentSha } : {}
-    },
-    changeSetId,
-    createdAt: now,
-    updatedAt: now
-  };
-  const review = createSuggestionMarkup(state.sidecar.reviewMarkdown ?? state.markdown, suggestion.patch, {
-    suggestionId: suggestion.id,
-    author,
-    message,
-    createdAt: now,
-    updatedAt: now
-  });
-  const nextSidecar = deriveSidecarFromReviewMarkdown(
-    { ...state.sidecar, reviewMarkdown: review.reviewMarkdown, anchors: [...state.sidecar.anchors, anchor] },
-    review.reviewMarkdown,
-    { author, baseHead: entry?.currentSha, now }
-  );
-  await writeSidecar(io, nextSidecar);
-  const enriched = nextSidecar.suggestions.find((candidate) => candidate.id === suggestion.id);
-  if (!enriched) throw new MdocsError("validation_error", `Could not derive suggestion ${suggestion.id}.`, "Refresh review state and try again.");
-  return enriched;
-}
-async function acceptSuggestion(io, suggestionId, actor = defaultActor()) {
-  const manifest = await indexWorkspace(io);
-  for (const entry of manifest.docs) {
-    const markdown = await io.readText(entry.path);
-    const sidecar = await readSidecar(io, entry.docId);
-    const suggestion = sidecar.suggestions.find((candidate) => candidate.id === suggestionId);
-    if (!suggestion) continue;
-    const now = nowIso();
-    const reviewMarkdown = sidecar.reviewMarkdown ?? markdown;
-    const resolvedReviewMarkdown = resolveSuggestionMarkup(reviewMarkdown, suggestionId, "accept");
-    const nextMarkdown = projectCanonicalMarkdown(resolvedReviewMarkdown);
-    assertCleanMarkdown(nextMarkdown);
-    const nextSidecar = deriveSidecarFromReviewMarkdown(
-      { ...sidecar, reviewMarkdown: resolvedReviewMarkdown },
-      resolvedReviewMarkdown,
-      { author: suggestion.author, baseHead: entry.currentSha, now }
-    );
-    await io.writeText(entry.path, nextMarkdown);
-    await writeSidecar(io, nextSidecar);
-    return resolvedSuggestion(suggestion, "accepted", actor, now);
+  const drafts = [];
+  const seenPaths = /* @__PURE__ */ new Set();
+  for (const path of markdownFiles) {
+    seenPaths.add(path);
+    const existing = existingByPath.get(path);
+    const stat4 = io.statFile ? await io.statFile(path).catch(() => void 0) : void 0;
+    const cached = cache?.get(path);
+    const statUnchanged = Boolean(stat4 && cached && cached.mtimeMs === stat4.mtimeMs && cached.size === stat4.size);
+    if (statUnchanged && cached) {
+      drafts.push({
+        entry: manifestEntry(cached.docId, path, cached.title, cached.contentHash, existing, now, stat4),
+        markdown: cached.markdown,
+        reusedFromCache: true
+      });
+      continue;
+    }
+    let markdown;
+    try {
+      markdown = await io.readText(path);
+      assertCleanMarkdown(markdown);
+    } catch (error) {
+      emitIndexDiagnostic(path, error);
+      if (existing) drafts.push({ entry: { ...existing }, markdown: cached?.markdown ?? "", reusedFromCache: true });
+      continue;
+    }
+    const contentHash = contentHashForText(markdown);
+    const title = titleFromMarkdown(path, markdown);
+    const docId = existing?.docId ?? mintDocId(options?.rootId, path);
+    drafts.push({
+      entry: manifestEntry(docId, path, title, contentHash, existing, now, stat4),
+      markdown,
+      reusedFromCache: false
+    });
   }
-  throw new MdocsError("not_found", `Unknown suggestion: ${suggestionId}`, "List suggestion ids with the suggestions command.");
-}
-async function rejectSuggestion(io, suggestionId, actor = defaultActor()) {
-  const manifest = await indexWorkspace(io);
-  for (const entry of manifest.docs) {
-    const sidecar = await readSidecar(io, entry.docId);
-    const suggestion = sidecar.suggestions.find((candidate) => candidate.id === suggestionId);
-    if (!suggestion) continue;
-    const now = nowIso();
-    const updated = resolvedSuggestion(suggestion, "rejected", actor, now);
-    const reviewMarkdown = resolveSuggestionMarkup(sidecar.reviewMarkdown ?? "", suggestionId, "reject");
-    const nextSidecar = deriveSidecarFromReviewMarkdown({ ...sidecar, reviewMarkdown }, reviewMarkdown, {
-      author: suggestion.author,
-      now
+  const docs = drafts.map((draft) => draft.entry);
+  const lookup = docs.map((entry) => ({ docId: entry.docId, path: entry.path, title: entry.title }));
+  const lookupSignature = JSON.stringify(lookup);
+  const reuseLinks = cache ? cacheLookupSignatures.get(cache) === lookupSignature : false;
+  const graphDocuments = [];
+  const markdownByPath = /* @__PURE__ */ new Map();
+  for (const draft of drafts) {
+    const { entry, markdown, reusedFromCache } = draft;
+    markdownByPath.set(entry.path, markdown);
+    const cached = cache?.get(entry.path);
+    const links = reusedFromCache && reuseLinks && cached?.links && cached.docId === entry.docId ? cached.links : resolveMarkdownLinks(extractMarkdownLinks(markdown), entry, lookup);
+    graphDocuments.push({
+      docId: entry.docId,
+      path: entry.path,
+      title: entry.title,
+      openComments: 0,
+      openSuggestions: 0,
+      anchorsNeedingReview: 0,
+      externalLinks: links.filter((link2) => link2.status === "external").length,
+      unresolvedLinks: links.filter((link2) => link2.status === "unresolved" || link2.status === "ambiguous").length,
+      links
     });
-    await writeSidecar(io, nextSidecar);
-    return updated;
+    if (cache && entry.mtimeMs !== void 0 && entry.size !== void 0) {
+      cache.set(entry.path, {
+        mtimeMs: entry.mtimeMs,
+        size: entry.size,
+        contentHash: entry.contentHash ?? contentHashForText(markdown),
+        markdown,
+        title: entry.title,
+        docId: entry.docId,
+        links
+      });
+    }
+  }
+  if (cache) {
+    cacheLookupSignatures.set(cache, lookupSignature);
+    for (const key of [...cache.keys()]) {
+      if (!seenPaths.has(key)) cache.delete(key);
+    }
   }
-  throw new MdocsError("not_found", `Unknown suggestion: ${suggestionId}`, "List suggestion ids with the suggestions command.");
+  const nextManifest = { ...baseline, docs, updatedAt: baseline.updatedAt };
+  if (stableManifestKey(baseline) === stableManifestKey(nextManifest)) {
+    return { manifest: baseline, graphDocuments, markdownByPath };
+  }
+  const written = { ...nextManifest, updatedAt: now };
+  await writeManifest(io, written);
+  return { manifest: written, graphDocuments, markdownByPath };
 }
-function resolvedSuggestion(suggestion, status, actor, now) {
+function manifestEntry(docId, path, title, contentHash, existing, now, stat4) {
   return {
-    ...suggestion,
-    status,
-    updatedAt: now,
-    resolvedAt: now,
-    resolvedBy: actor
+    docId,
+    path,
+    title,
+    contentHash,
+    currentSha: existing?.currentSha,
+    // Preserve the prior timestamp when the content is unchanged so the manifest
+    // stays byte-identical; only a real content change advances it.
+    updatedAt: existing && existing.contentHash === contentHash ? existing.updatedAt : now,
+    ...stat4 ? { mtimeMs: stat4.mtimeMs, size: stat4.size } : {}
   };
 }
-async function resolveComment(io, commentId, actor = defaultActor()) {
-  const manifest = await indexWorkspace(io);
-  for (const entry of manifest.docs) {
-    const sidecar = await readSidecar(io, entry.docId);
-    const comment2 = sidecar.comments.find((candidate) => candidate.id === commentId);
-    if (!comment2) continue;
-    const now = nowIso();
-    const updated = {
-      ...comment2,
-      status: "resolved",
-      updatedAt: now,
-      resolvedAt: now,
-      resolvedBy: actor
-    };
-    await writeSidecar(io, {
-      ...sidecar,
-      comments: sidecar.comments.map((candidate) => candidate.id === commentId ? updated : candidate),
-      updatedAt: now
-    });
-    return updated;
-  }
-  throw new MdocsError("not_found", `Unknown comment: ${commentId}`, "List comment ids with the comments command.");
+function mintDocId(rootId, path) {
+  return rootId ? deterministicDocId(rootId, path) : createDocId();
 }
-function createEmptySidecar(entry) {
-  return {
-    schemaVersion: SIDECAR_SCHEMA_VERSION,
-    docId: entry.docId,
-    path: entry.path,
-    title: entry.title,
-    anchors: [],
-    comments: [],
-    suggestions: [],
-    changeSets: [],
-    updatedAt: entry.updatedAt
-  };
+function stableManifestKey(manifest) {
+  return JSON.stringify({ ...manifest, updatedAt: "" });
 }
-function sidecarPath(docId) {
-  return `${SIDECAR_DIR}/${docId}.json`;
+function emitIndexDiagnostic(path, error) {
+  const detail = error instanceof Error ? error.message : String(error);
+  if (typeof process !== "undefined" && process.stderr && typeof process.stderr.write === "function") {
+    process.stderr.write(`mdocs index skipped ${path}: ${detail}
+`);
+  }
 }
 async function readManifest(io) {
   const raw = await io.readText(MANIFEST_PATH);
@@ -1952,79 +1275,21 @@ async function writeManifest(io, manifest) {
   await writeJsonText(io, MANIFEST_PATH, `${JSON.stringify(manifest, null, 2)}
 `);
 }
-async function readSidecar(io, docId) {
-  const raw = await io.readText(sidecarPath(docId));
-  return JSON.parse(raw);
-}
-async function writeSidecar(io, sidecar) {
-  await writeJsonText(io, sidecarPath(sidecar.docId), `${JSON.stringify(sidecar, null, 2)}
-`);
-}
-async function writeJsonText(io, path, content) {
-  if (io.writeTextAtomic) {
-    await io.writeTextAtomic(path, content);
-    return;
-  }
-  await io.writeText(path, content);
-}
 function findDoc(manifest, pathOrDocId) {
   const entry = manifest.docs.find((doc) => doc.path === pathOrDocId || doc.docId === pathOrDocId);
-  if (!entry) throw new Error(`Unknown document: ${pathOrDocId}`);
+  if (!entry) throw new MdocsError("not_found", `Unknown document: ${pathOrDocId}`);
   return entry;
 }
 async function readManifestIfPresent(io) {
   if (!await io.exists(MANIFEST_PATH)) return void 0;
   return readManifest(io);
 }
-async function ensureDocumentSidecar(io, entry, markdown) {
-  const path = sidecarPath(entry.docId);
-  if (await io.exists(path)) {
-    const sidecar = await readSidecar(io, entry.docId).catch(() => createEmptySidecar(entry));
-    await writeSidecar(io, {
-      ...sidecar,
-      path: entry.path,
-      title: entry.title,
-      anchors: remapAnchors(markdown, sidecar.anchors),
-      updatedAt: nowIso()
-    });
+async function writeJsonText(io, path, content) {
+  if (io.writeTextAtomic) {
+    await io.writeTextAtomic(path, content);
     return;
   }
-  await writeSidecar(io, createEmptySidecar(entry));
-}
-async function findRenamedDocumentEntry(io, candidates, markdown, contentHash, newPathCountForHash) {
-  if (newPathCountForHash === 1) {
-    const hashMatches = candidates.filter((entry) => entry.contentHash === contentHash);
-    if (hashMatches.length === 1) return hashMatches[0];
-  }
-  const scored = [];
-  for (const entry of candidates) {
-    const path = sidecarPath(entry.docId);
-    if (!await io.exists(path)) continue;
-    const sidecar = await readSidecar(io, entry.docId).catch(() => void 0);
-    if (!sidecar) continue;
-    const score = sidecarMarkdownMatchScore(sidecar, markdown);
-    if (score > 0) scored.push({ entry, score });
-  }
-  scored.sort((left, right) => right.score - left.score);
-  const best = scored[0];
-  const runnerUp = scored[1];
-  return best && best.score > (runnerUp?.score ?? 0) ? best.entry : void 0;
-}
-function sidecarMarkdownMatchScore(sidecar, markdown) {
-  const needles = /* @__PURE__ */ new Set();
-  for (const anchor of sidecar.anchors) {
-    const quote = anchor.selector.quote.trim();
-    if (quote) needles.add(quote);
-  }
-  for (const suggestion of sidecar.suggestions) {
-    if (suggestion.patch.before.trim()) needles.add(suggestion.patch.before.trim());
-    if (suggestion.patch.after.trim()) needles.add(suggestion.patch.after.trim());
-  }
-  let score = 0;
-  for (const needle of needles) {
-    if (markdown.includes(needle)) score += 1;
-  }
-  return score;
+  await io.writeText(path, content);
 }
 
 // ../core/src/context.ts
@@ -2043,8 +1308,6 @@ function sliceMarkdown(markdown, startLine, endLine) {
   return { markdown: lines.slice(sl - 1, el).join("\n"), totalLines, startLine: sl, endLine: el };
 }
 function summarizeDocumentContext(document) {
-  const comments = openComments(document);
-  const suggestions = openSuggestions(document);
   const currentSha = currentDocumentSha(document);
   return {
     docId: document.docId,
@@ -2055,9 +1318,9 @@ function summarizeDocumentContext(document) {
     byteLength: new TextEncoder().encode(document.markdown).byteLength,
     headings: extractMarkdownHeadings(document.markdown),
     reviewCounts: {
-      openComments: comments.length,
-      openSuggestions: suggestions.length,
-      anchorsNeedingReview: document.anchors.filter((anchor) => anchor.status !== "mapped").length
+      openComments: document.openComments,
+      openSuggestions: document.openSuggestions,
+      anchorsNeedingReview: document.anchorsNeedingReview
     },
     imageCounts: imageCounts(document.images),
     linkCounts: linkCounts(document.links)
@@ -2070,9 +1333,12 @@ function reviewStateForDocument(document) {
     path: document.path,
     title: document.title,
     ...currentSha ? { currentSha } : {},
-    comments: openComments(document),
-    suggestions: openSuggestions(document),
-    anchors: document.anchors
+    reviewCounts: {
+      openComments: document.openComments,
+      openSuggestions: document.openSuggestions,
+      anchorsNeedingReview: document.anchorsNeedingReview
+    },
+    message: "Review state is authority-backed. Use remote authority commands or MCP endpoints for comments, suggestions, accept, and reject."
   };
 }
 function currentDocumentSha(document) {
@@ -2101,12 +1367,6 @@ function extractMarkdownHeadings(markdown) {
   });
   return headings;
 }
-function openComments(document) {
-  return document.sidecar.comments.filter((comment2) => comment2.status === "open");
-}
-function openSuggestions(document) {
-  return document.sidecar.suggestions.filter((suggestion) => suggestion.status === "open");
-}
 function imageCounts(images) {
   const local = images.filter((image2) => image2.isLocal).length;
   return {
@@ -4844,7 +4104,8 @@ var canonicalSchema = new Schema({
   nodes: {
     // The doc allows suggestion marks on its block children so pending
     // block-level suggestions (node marks) survive fromJSON and can be
-    // structurally reverted before serialization.
+    // structurally resolved before serialization. Only inline insert/delete is
+    // used today; block-level (modification) is reserved for a later pass.
     doc: { content: "block+", marks: "insertion deletion modification" },
     paragraph: { group: "block", content: "inline*", attrs: blockAttrs },
     heading: {
@@ -4926,11 +4187,14 @@ var canonicalSchema = new Schema({
     strike: {},
     code: {},
     // Pending-suggestion marks (mirroring the web editor's extensions). They
-    // are never serialized — the canonical serializer reverts them first —
-    // but the schema must know them so suggestion-marked docs load intact.
+    // never appear in canonical bytes — the canonical serializer resolves them
+    // first — but the schema must know them so suggestion-marked docs load and
+    // the CriticMarkup codec can emit/parse them. `id` tags a rendered span
+    // with its owning branch at overlay time; it is empty while editing one
+    // branch.
     insertion: {
       attrs: { id: { default: null } },
-      inclusive: false,
+      inclusive: true,
       excludes: "deletion modification insertion"
     },
     deletion: {
@@ -11016,6 +10280,69 @@ var MarkdownSerializerState = class {
   }
 };
 
+// ../core/src/suggestion-id.ts
+var SUGGESTION_ID_PREFIX = "suggestion:";
+
+// ../core/src/critic-markup.ts
+var INSERTION_OPEN_SENTINEL = String.fromCharCode(57344);
+var INSERTION_CLOSE_SENTINEL = String.fromCharCode(57345);
+var DELETION_OPEN_SENTINEL = String.fromCharCode(57346);
+var DELETION_CLOSE_SENTINEL = String.fromCharCode(57347);
+var ID_OPEN_SENTINEL = String.fromCharCode(57348);
+var ID_CLOSE_SENTINEL = String.fromCharCode(57349);
+function suggestionSpanAt(src, start) {
+  const open = src.slice(start, start + 3);
+  if (open === "{++") return { markName: "insertion", closeSequence: "++}" };
+  if (open === "{--") return { markName: "deletion", closeSequence: "--}" };
+  return void 0;
+}
+function suggestionIdSuffixAt(src, pos) {
+  if (!src.startsWith("{#", pos)) return void 0;
+  const end = src.indexOf("}", pos + 2);
+  if (end === -1) return void 0;
+  const id = src.slice(pos + 2, end);
+  return id.startsWith(SUGGESTION_ID_PREFIX) ? id : void 0;
+}
+function findUnescapedClose(src, from, closeSequence) {
+  let pos = from;
+  while (pos < src.length) {
+    if (src.charCodeAt(pos) === 92) {
+      pos += 2;
+      continue;
+    }
+    if (src.startsWith(closeSequence, pos)) return pos;
+    pos += 1;
+  }
+  return -1;
+}
+function criticMarkupPlugin(md) {
+  md.inline.ruler.before("emphasis", "criticmarkup", (state, silent) => {
+    const start = state.pos;
+    if (state.src.charCodeAt(start) !== 123) return false;
+    const span = suggestionSpanAt(state.src, start);
+    if (!span) return false;
+    const contentStart = start + 3;
+    const closeStart = findUnescapedClose(state.src, contentStart, span.closeSequence);
+    if (closeStart === -1) return false;
+    if (silent) return true;
+    const openToken = state.push(`${span.markName}_open`, "", 1);
+    const savedMax = state.posMax;
+    state.pos = contentStart;
+    state.posMax = closeStart;
+    state.md.inline.tokenize(state);
+    state.posMax = savedMax;
+    state.push(`${span.markName}_close`, "", -1);
+    let nextPos = closeStart + span.closeSequence.length;
+    const id = suggestionIdSuffixAt(state.src, nextPos);
+    if (id !== void 0) {
+      openToken.attrSet("id", id);
+      nextPos += `{#${id}}`.length;
+    }
+    state.pos = nextPos;
+    return true;
+  });
+}
+
 // ../core/src/pm-markdown.ts
 function serializeInlineFragmentToMarkdown(node) {
   const paragraph2 = canonicalSchema.nodes.paragraph;
@@ -11058,109 +10385,119 @@ function backtickFence(node) {
   const longest = matches.reduce((length, run) => Math.max(length, run.length), 2);
   return "`".repeat(longest + 1);
 }
-var markdownSerializer = new MarkdownSerializer(
-  {
-    paragraph(state, node) {
-      state.renderInline(node);
-      state.closeBlock(node);
-    },
-    heading(state, node) {
-      state.write(`${"#".repeat(Number(node.attrs.level) || 1)} `);
-      state.renderInline(node, false);
-      state.closeBlock(node);
-    },
-    blockquote(state, node) {
-      state.wrapBlock("> ", null, node, () => state.renderContent(node));
-    },
-    codeBlock(state, node) {
-      const fence2 = backtickFence(node);
-      state.write(`${fence2}${typeof node.attrs.language === "string" ? node.attrs.language : ""}
+var NODE_SERIALIZERS = {
+  paragraph(state, node) {
+    state.renderInline(node);
+    state.closeBlock(node);
+  },
+  heading(state, node) {
+    state.write(`${"#".repeat(Number(node.attrs.level) || 1)} `);
+    state.renderInline(node, false);
+    state.closeBlock(node);
+  },
+  blockquote(state, node) {
+    state.wrapBlock("> ", null, node, () => state.renderContent(node));
+  },
+  codeBlock(state, node) {
+    const fence2 = backtickFence(node);
+    state.write(`${fence2}${typeof node.attrs.language === "string" ? node.attrs.language : ""}
 `);
-      state.text(node.textContent, false);
-      state.ensureNewLine();
-      state.write(fence2);
-      state.closeBlock(node);
-    },
-    horizontalRule(state, node) {
-      state.write("---");
-      state.closeBlock(node);
-    },
-    bulletList(state, node) {
-      state.renderList(node, "  ", () => "- ");
-    },
-    orderedList(state, node) {
-      const start = Number(node.attrs.start) || 1;
-      const maxWidth = String(start + node.childCount - 1).length;
-      const space = state.repeat(" ", maxWidth + 2);
-      state.renderList(node, space, (index) => {
-        const label = String(start + index);
-        return `${state.repeat(" ", maxWidth - label.length)}${label}. `;
-      });
-    },
-    listItem(state, node) {
-      state.renderContent(node);
-    },
-    taskList(state, node) {
-      state.renderList(node, "  ", () => "- ");
-    },
-    taskItem(state, node) {
-      state.write(`[${node.attrs.checked ? "x" : " "}] `);
-      state.renderContent(node);
-    },
-    table: serializeTable,
-    image(state, node) {
-      const src = typeof node.attrs.src === "string" ? node.attrs.src : "";
-      const alt = typeof node.attrs.alt === "string" ? node.attrs.alt : "";
-      const title = typeof node.attrs.title === "string" ? node.attrs.title : "";
-      const destination = src.replace(/[()"]/g, "\\$&");
-      const titleSuffix = title ? ` "${title.replace(/["\\]/g, "\\$&")}"` : "";
-      state.write(`![${escapeImageAlt(alt)}](${destination}${titleSuffix})`);
-    },
-    hardBreak(state, node, parent, index) {
-      for (let after = index + 1; after < parent.childCount; after += 1) {
-        if (parent.child(after).type !== node.type) {
-          state.write("\\\n");
-          return;
-        }
+    state.text(node.textContent, false);
+    state.ensureNewLine();
+    state.write(fence2);
+    state.closeBlock(node);
+  },
+  horizontalRule(state, node) {
+    state.write("---");
+    state.closeBlock(node);
+  },
+  bulletList(state, node) {
+    state.renderList(node, "  ", () => "- ");
+  },
+  orderedList(state, node) {
+    const start = Number(node.attrs.start) || 1;
+    const maxWidth = String(start + node.childCount - 1).length;
+    const space = state.repeat(" ", maxWidth + 2);
+    state.renderList(node, space, (index) => {
+      const label = String(start + index);
+      return `${state.repeat(" ", maxWidth - label.length)}${label}. `;
+    });
+  },
+  listItem(state, node) {
+    state.renderContent(node);
+  },
+  taskList(state, node) {
+    state.renderList(node, "  ", () => "- ");
+  },
+  taskItem(state, node) {
+    state.write(`[${node.attrs.checked ? "x" : " "}] `);
+    state.renderContent(node);
+  },
+  table: serializeTable,
+  image(state, node) {
+    const src = typeof node.attrs.src === "string" ? node.attrs.src : "";
+    const alt = typeof node.attrs.alt === "string" ? node.attrs.alt : "";
+    const title = typeof node.attrs.title === "string" ? node.attrs.title : "";
+    const destination = src.replace(/[()"]/g, "\\$&");
+    const titleSuffix = title ? ` "${title.replace(/["\\]/g, "\\$&")}"` : "";
+    state.write(`![${escapeImageAlt(alt)}](${destination}${titleSuffix})`);
+  },
+  hardBreak(state, node, parent, index) {
+    for (let after = index + 1; after < parent.childCount; after += 1) {
+      if (parent.child(after).type !== node.type) {
+        state.write("\\\n");
+        return;
       }
-    },
-    text(state, node) {
-      state.text(node.text ?? "");
     }
   },
-  {
-    bold: { open: "**", close: "**", mixable: true, expelEnclosingWhitespace: true },
-    italic: { open: "_", close: "_", mixable: true, expelEnclosingWhitespace: true },
-    strike: { open: "~~", close: "~~", mixable: true, expelEnclosingWhitespace: true },
-    code: {
-      open(_state, _mark, parent, index) {
-        return backticksFor2(parent.child(index), -1);
-      },
-      close(_state, _mark, parent, index) {
-        return backticksFor2(parent.child(index - 1), 1);
-      },
-      escape: false
+  text(state, node) {
+    state.text(node.text ?? "");
+  }
+};
+var BASE_MARK_SERIALIZERS = {
+  bold: { open: "**", close: "**", mixable: true, expelEnclosingWhitespace: true },
+  italic: { open: "_", close: "_", mixable: true, expelEnclosingWhitespace: true },
+  strike: { open: "~~", close: "~~", mixable: true, expelEnclosingWhitespace: true },
+  code: {
+    open(_state, _mark, parent, index) {
+      return backticksFor2(parent.child(index), -1);
     },
-    link: {
-      open: "[",
-      close(_state, mark) {
-        const href = typeof mark.attrs.href === "string" ? mark.attrs.href : "";
-        return `](${href.replace(/[()"]/g, "\\$&")})`;
-      },
-      mixable: false
+    close(_state, _mark, parent, index) {
+      return backticksFor2(parent.child(index - 1), 1);
     },
-    wikilink: {
-      open(_state, mark, parent, index) {
-        const target = typeof mark.attrs.target === "string" ? mark.attrs.target : "";
-        const label = markedRangeText(parent, index, mark);
-        if (!target || label === target) return "[[";
-        return `[[${target}|`;
-      },
-      close: "]]",
-      mixable: false
-    }
+    escape: false
+  },
+  link: {
+    open: "[",
+    close(_state, mark) {
+      const href = typeof mark.attrs.href === "string" ? mark.attrs.href : "";
+      return `](${href.replace(/[()"]/g, "\\$&")})`;
+    },
+    mixable: false
+  },
+  wikilink: {
+    open(_state, mark, parent, index) {
+      const target = typeof mark.attrs.target === "string" ? mark.attrs.target : "";
+      const label = markedRangeText(parent, index, mark);
+      if (!target || label === target) return "[[";
+      return `[[${target}|`;
+    },
+    close: "]]",
+    mixable: false
   }
-);
+};
+var markdownSerializer = new MarkdownSerializer(NODE_SERIALIZERS, BASE_MARK_SERIALIZERS);
+function suggestionMarkClose(closeSentinel) {
+  return (_state, mark) => {
+    const id = typeof mark.attrs.id === "string" ? mark.attrs.id : "";
+    return id ? `${closeSentinel}${ID_OPEN_SENTINEL}${id}${ID_CLOSE_SENTINEL}` : closeSentinel;
+  };
+}
+var criticMarkupSerializer = new MarkdownSerializer(NODE_SERIALIZERS, {
+  ...BASE_MARK_SERIALIZERS,
+  insertion: { open: INSERTION_OPEN_SENTINEL, close: suggestionMarkClose(INSERTION_CLOSE_SENTINEL), mixable: true },
+  deletion: { open: DELETION_OPEN_SENTINEL, close: suggestionMarkClose(DELETION_CLOSE_SENTINEL), mixable: true }
+});
 function markedRangeText(parent, index, mark) {
   let text2 = "";
   for (let childIndex = index; childIndex < parent.childCount; childIndex += 1) {
@@ -11187,7 +10524,7 @@ function backticksFor2(node, side) {
 }
 
 // ../core/src/pm-parse.ts
-var parser = new MarkdownParser(canonicalSchema, new lib_default(), {
+var BASE_TOKEN_SPEC = {
   blockquote: { block: "blockquote" },
   paragraph: { block: "paragraph" },
   list_item: { block: "listItem" },
@@ -11214,56 +10551,246 @@ var parser = new MarkdownParser(canonicalSchema, new lib_default(), {
       title: tok.attrGet("title")
     })
   }
+};
+var parser = new MarkdownParser(canonicalSchema, new lib_default(), BASE_TOKEN_SPEC);
+var criticMarkupParser = new MarkdownParser(canonicalSchema, new lib_default().use(criticMarkupPlugin), {
+  ...BASE_TOKEN_SPEC,
+  insertion: { mark: "insertion", getAttrs: (tok) => ({ id: tok.attrGet("id") }) },
+  deletion: { mark: "deletion", getAttrs: (tok) => ({ id: tok.attrGet("id") }) }
 });
 
-// ../core/src/remote-document-io.ts
-var RemoteDocumentIO = class {
-  constructor(document) {
-    this.document = document;
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    const manifest = {
-      schemaVersion: document.sidecar.schemaVersion,
-      workspaceId: document.workspaceId,
-      createdAt: now,
-      updatedAt: now,
-      docs: [{
-        docId: document.docId,
-        path: document.path,
-        title: document.title,
-        contentHash: contentHashForText(document.markdown),
-        currentSha: document.currentSha,
-        updatedAt: document.sidecar.updatedAt
-      }]
-    };
-    this.files.set(MANIFEST_PATH, `${JSON.stringify(manifest, null, 2)}
-`);
-    this.files.set(document.path, document.markdown);
-    this.files.set(sidecarPath(document.docId), `${JSON.stringify(document.sidecar, null, 2)}
-`);
+// ../core/src/patch.ts
+var PATCH_SCHEMA = "magic-markdown.patch.v1";
+function textPatchHash(text2) {
+  return contentHashForText(text2);
+}
+function buildPatchEnvelope(options) {
+  const ops = diffToPatchOps(options.base, options.result);
+  return patchEnvelopeFromOps({
+    baseVersion: options.baseVersion,
+    base: options.base,
+    ops,
+    clientMutationId: options.clientMutationId,
+    clientMeta: options.clientMeta
+  });
+}
+function buildLineRangePatchEnvelope(options) {
+  assertLineRangeWithin(options.base, options.range);
+  const result = replaceLineRange(options.base, options.range, options.replacement);
+  return buildPatchEnvelope({
+    baseVersion: options.baseVersion,
+    base: options.base,
+    result,
+    clientMutationId: options.clientMutationId,
+    clientMeta: { ...options.clientMeta ?? {}, source: options.clientMeta?.source ?? "line_range" }
+  });
+}
+function patchEnvelopeFromOps(options) {
+  const ops = normalizePatchOps(options.ops);
+  const result = applyPatchOps(options.base, ops);
+  return {
+    schema: PATCH_SCHEMA,
+    baseVersion: options.baseVersion,
+    baseHash: textPatchHash(options.base),
+    baseLength: options.base.length,
+    resultLength: result.length,
+    resultHash: textPatchHash(result),
+    ops,
+    ...options.clientMutationId ? { clientMutationId: options.clientMutationId } : {},
+    ...options.clientMeta ? { clientMeta: options.clientMeta } : {}
+  };
+}
+function applyPatchOps(base, ops) {
+  validatePatchOpsShape(ops);
+  let baseCursor = 0;
+  let result = "";
+  for (const op of ops) {
+    if (op.type === "retain") {
+      const next = baseCursor + op.count;
+      if (next > base.length) throw new MdocsError("validation_error", "Patch retain runs past the base document.");
+      result += base.slice(baseCursor, next);
+      baseCursor = next;
+      continue;
+    }
+    if (op.type === "delete") {
+      const actual = base.slice(baseCursor, baseCursor + op.text.length);
+      if (actual !== op.text) throw new MdocsError("conflict", "Patch delete text does not match the base document.");
+      baseCursor += op.text.length;
+      continue;
+    }
+    result += op.text;
+  }
+  return result + base.slice(baseCursor);
+}
+function normalizePatchOps(ops) {
+  validatePatchOpsShape(ops);
+  const normalized = [];
+  for (const op of ops) {
+    if (op.type === "retain" && op.count === 0) continue;
+    if ((op.type === "insert" || op.type === "delete") && op.text.length === 0) continue;
+    const last = normalized.at(-1);
+    if (last?.type === op.type) {
+      if (op.type === "retain" && last.type === "retain") last.count += op.count;
+      if (op.type === "insert" && last.type === "insert") last.text += op.text;
+      if (op.type === "delete" && last.type === "delete") last.text += op.text;
+      continue;
+    }
+    normalized.push({ ...op });
   }
-  document;
-  files = /* @__PURE__ */ new Map();
-  async readText(path) {
-    const content = this.files.get(path);
-    if (content === void 0) throw new Error(`Missing remote document file: ${path}`);
-    return content;
+  return normalized;
+}
+function diffToPatchOps(base, result) {
+  if (base === result) return [];
+  let prefix = 0;
+  while (prefix < base.length && prefix < result.length && base[prefix] === result[prefix]) prefix += 1;
+  let suffix = 0;
+  while (suffix < base.length - prefix && suffix < result.length - prefix && base[base.length - 1 - suffix] === result[result.length - 1 - suffix]) {
+    suffix += 1;
+  }
+  const tokenRefined = diffMiddleByTokens(base, result, prefix, suffix);
+  if (tokenRefined) return tokenRefined;
+  const refined = diffMiddleByLines(base, result, prefix, suffix);
+  if (refined) return refined;
+  return singleWindowPatchOps(base, result, prefix, suffix);
+}
+function singleWindowPatchOps(base, result, prefix, suffix) {
+  const ops = [];
+  if (prefix > 0) ops.push({ type: "retain", count: prefix });
+  const deleted = base.slice(prefix, base.length - suffix);
+  const inserted = result.slice(prefix, result.length - suffix);
+  if (deleted.length > 0) ops.push({ type: "delete", text: deleted });
+  if (inserted.length > 0) ops.push({ type: "insert", text: inserted });
+  if (suffix > 0) ops.push({ type: "retain", count: suffix });
+  return normalizePatchOps(ops);
+}
+function diffMiddleByLines(base, result, prefix, suffix) {
+  const baseMiddle = base.slice(prefix, base.length - suffix);
+  const resultMiddle = result.slice(prefix, result.length - suffix);
+  if (!baseMiddle.includes("\n") && !resultMiddle.includes("\n")) return void 0;
+  const baseLines = splitLinesPreservingNewline(baseMiddle);
+  const resultLines = splitLinesPreservingNewline(resultMiddle);
+  if (baseLines.length + resultLines.length > 800) return void 0;
+  if (!hasSharedLine(baseLines, resultLines)) return void 0;
+  const middleOps = lineDiffOps(baseLines, resultLines);
+  if (middleOps.length <= 2) return void 0;
+  const ops = [];
+  if (prefix > 0) ops.push({ type: "retain", count: prefix });
+  ops.push(...middleOps);
+  if (suffix > 0) ops.push({ type: "retain", count: suffix });
+  return normalizePatchOps(ops);
+}
+function diffMiddleByTokens(base, result, prefix, suffix) {
+  const baseMiddle = base.slice(prefix, base.length - suffix);
+  const resultMiddle = result.slice(prefix, result.length - suffix);
+  if (!baseMiddle || !resultMiddle) return void 0;
+  const baseTokens = tokenizePatchMiddle(baseMiddle);
+  const resultTokens = tokenizePatchMiddle(resultMiddle);
+  if (baseTokens.length + resultTokens.length > 1200) return void 0;
+  if (!hasSharedToken(baseTokens, resultTokens)) return void 0;
+  const middleOps = tokenDiffOps(baseTokens, resultTokens);
+  if (!middleOps.some((op) => op.type === "retain")) return void 0;
+  const ops = [];
+  if (prefix > 0) ops.push({ type: "retain", count: prefix });
+  ops.push(...middleOps);
+  if (suffix > 0) ops.push({ type: "retain", count: suffix });
+  const normalized = normalizePatchOps(ops);
+  return normalized.length > 3 ? normalized : void 0;
+}
+function tokenizePatchMiddle(text2) {
+  return text2.match(/[\p{L}\p{N}_]+|\s+|[^\s\p{L}\p{N}_]+/gu) ?? [];
+}
+function hasSharedToken(first, second) {
+  const secondSet = new Set(second);
+  return first.some((token) => secondSet.has(token));
+}
+function tokenDiffOps(baseTokens, resultTokens) {
+  const lcs = tokenLcsTable(baseTokens, resultTokens);
+  const ops = [];
+  let baseIndex = 0;
+  let resultIndex = 0;
+  while (baseIndex < baseTokens.length || resultIndex < resultTokens.length) {
+    if (baseIndex < baseTokens.length && resultIndex < resultTokens.length && baseTokens[baseIndex] === resultTokens[resultIndex]) {
+      ops.push({ type: "retain", count: baseTokens[baseIndex].length });
+      baseIndex += 1;
+      resultIndex += 1;
+      continue;
+    }
+    if (resultIndex >= resultTokens.length || baseIndex < baseTokens.length && lcs[baseIndex + 1][resultIndex] >= lcs[baseIndex][resultIndex + 1]) {
+      ops.push({ type: "delete", text: baseTokens[baseIndex] });
+      baseIndex += 1;
+      continue;
+    }
+    ops.push({ type: "insert", text: resultTokens[resultIndex] });
+    resultIndex += 1;
   }
-  async writeText(path, content) {
-    this.files.set(path, content);
+  return normalizePatchOps(ops);
+}
+function tokenLcsTable(baseTokens, resultTokens) {
+  const table2 = Array.from({ length: baseTokens.length + 1 }, () => Array.from({ length: resultTokens.length + 1 }, () => 0));
+  for (let baseIndex = baseTokens.length - 1; baseIndex >= 0; baseIndex -= 1) {
+    for (let resultIndex = resultTokens.length - 1; resultIndex >= 0; resultIndex -= 1) {
+      table2[baseIndex][resultIndex] = baseTokens[baseIndex] === resultTokens[resultIndex] ? table2[baseIndex + 1][resultIndex + 1] + 1 : Math.max(table2[baseIndex + 1][resultIndex], table2[baseIndex][resultIndex + 1]);
+    }
   }
-  async exists(path) {
-    return this.files.has(path) || [...this.files.keys()].some((candidate) => candidate.startsWith(`${path}/`));
+  return table2;
+}
+function splitLinesPreservingNewline(text2) {
+  return text2.match(/[^\n]*\n|[^\n]+/g) ?? [];
+}
+function hasSharedLine(first, second) {
+  const secondSet = new Set(second);
+  return first.some((line) => secondSet.has(line));
+}
+function lineDiffOps(baseLines, resultLines) {
+  const lcs = lineLcsTable(baseLines, resultLines);
+  const ops = [];
+  let baseIndex = 0;
+  let resultIndex = 0;
+  while (baseIndex < baseLines.length || resultIndex < resultLines.length) {
+    if (baseIndex < baseLines.length && resultIndex < resultLines.length && baseLines[baseIndex] === resultLines[resultIndex]) {
+      ops.push({ type: "retain", count: baseLines[baseIndex].length });
+      baseIndex += 1;
+      resultIndex += 1;
+      continue;
+    }
+    if (resultIndex >= resultLines.length || baseIndex < baseLines.length && lcs[baseIndex + 1][resultIndex] >= lcs[baseIndex][resultIndex + 1]) {
+      ops.push({ type: "delete", text: baseLines[baseIndex] });
+      baseIndex += 1;
+      continue;
+    }
+    ops.push({ type: "insert", text: resultLines[resultIndex] });
+    resultIndex += 1;
   }
-  async mkdir() {
-    return;
+  return normalizePatchOps(ops);
+}
+function lineLcsTable(baseLines, resultLines) {
+  const table2 = Array.from({ length: baseLines.length + 1 }, () => Array.from({ length: resultLines.length + 1 }, () => 0));
+  for (let baseIndex = baseLines.length - 1; baseIndex >= 0; baseIndex -= 1) {
+    for (let resultIndex = resultLines.length - 1; resultIndex >= 0; resultIndex -= 1) {
+      table2[baseIndex][resultIndex] = baseLines[baseIndex] === resultLines[resultIndex] ? table2[baseIndex + 1][resultIndex + 1] + 1 : Math.max(table2[baseIndex + 1][resultIndex], table2[baseIndex][resultIndex + 1]);
+    }
   }
-  async listMarkdownFiles() {
-    return [this.document.path];
+  return table2;
+}
+function validatePatchOpsShape(ops) {
+  if (!Array.isArray(ops)) throw new MdocsError("validation_error", "Patch ops must be an array.");
+  for (const op of ops) {
+    if (op.type === "retain") {
+      if (!Number.isInteger(op.count) || op.count < 0) {
+        throw new MdocsError("validation_error", "Patch retain count must be a non-negative integer.");
+      }
+      continue;
+    }
+    if (op.type === "insert" || op.type === "delete") {
+      if (typeof op.text !== "string") throw new MdocsError("validation_error", `Patch ${op.type} text must be a string.`);
+      continue;
+    }
+    throw new MdocsError("validation_error", `Unknown patch op type: ${op.type}.`);
   }
-};
+}
 
 // src/agent.ts
-var CLI_VERSION = "0.3.20";
+var CLI_VERSION = "0.3.25";
 var CLI_PACKAGE_NAME = "@magic-markdown/cli";
 var AGENT_COMMANDS = [
   {
@@ -11351,12 +10878,12 @@ var AGENT_COMMANDS = [
       "Use remote status --json immediately after joining when the handoff includes expected scope/root/doc values. If it reports wrong_binding, stop and ask for the correct share or connector.",
       "Use remote context --summary --json first on file-scoped joins and before reading large documents. It returns metadata, heading line numbers, current head, review counts, and suggested next commands without dumping Markdown.",
       "remote context accepts --start-line and --end-line (1-based, inclusive) to page through large documents. The response always includes totalLines, startLine, and endLine \u2014 if totalLines > endLine, request the next page with --start-line <endLine+1>.",
-      "Use remote context --no-review when reading document content only; use remote review to list open comments, open suggestions, and anchors separately.",
+      "Use remote context --no-review when reading document content only; use remote review to list authority-projected open comments and suggestions separately.",
       "remote map works on project and workspace-scoped joins. Workspace-scoped map lists every shared Home root; target duplicate paths as <rootId>:<path-or-docId>.",
       "remote graph requires a project-scoped join and returns the shared project's Obsidian-style Markdown/wikilink graph.",
       "remote create-file and remote move-file require a project-scoped join and edit access. They write through the root sync API, so version history and conflict handling stay intact.",
       "remote library, create-folder, update-folder, move-root, and invite-folder use the organization suite on top of the joined project. Folder invites require admin access on the joined root and can only target folders containing that root.",
-      "remote comment/suggest never clobber concurrent edits: the server merges review additions, and the CLI rebases and retries automatically if a conflict still occurs.",
+      "remote comment/suggest never clobber concurrent edits: comments, suggestions, accept, and reject go through DocumentAuthority.",
       "remote reject <suggestionId> withdraws a suggestion you submitted (for example, a duplicate). You can always withdraw your own; rejecting another author's suggestion requires edit access, and resolving a human's review work needs the user's explicit ask.",
       "remote events returns truncated: true when older events were dropped from the bounded log; refetch with remote context --summary, then read needed content pages and remote review instead of trusting the gap.",
       "Agents have suggest-only access by default: comments and suggestions work, direct content rewrites are rejected with a forbidden_role error unless a human grants edit access.",
@@ -11365,7 +10892,7 @@ var AGENT_COMMANDS = [
   },
   {
     name: "doctor",
-    summary: "Validate the workspace map, sidecars, and agent interface readiness.",
+    summary: "Validate the workspace map and agent interface readiness.",
     usage: "mdocs doctor --json",
     output: "json",
     mutates: true,
@@ -11393,7 +10920,7 @@ var AGENT_COMMANDS = [
   },
   {
     name: "context",
-    summary: "Return agent-ready document Markdown, optional review state, image references, and resolved outgoing links.",
+    summary: "Return agent-ready clean Markdown, image references, and resolved outgoing links.",
     usage: "mdocs context <path|docId> [--summary] [--no-review] [--start-line N] [--end-line N] --json",
     output: "json",
     mutates: true,
@@ -11407,12 +10934,12 @@ var AGENT_COMMANDS = [
       "--summary returns metadata, heading line numbers, review counts, image counts, and link counts without returning Markdown.",
       "The response always includes totalLines, startLine, and endLine. If totalLines > endLine, request the next page with --start-line <endLine+1>.",
       "--start-line and --end-line are 1-based and inclusive. Omitting both returns the full document.",
-      "--no-review omits comments, suggestions, and anchors from content reads; use review/comments/suggestions commands when you need review state."
+      "--no-review omits authority-review redirect metadata from content reads. Use remote review for comments and suggestions."
     ]
   },
   {
     name: "review",
-    summary: "Return open comments, open suggestions, and anchors for one document without returning Markdown.",
+    summary: "Return local authority-review redirect metadata for one document without returning Markdown.",
     usage: "mdocs review <path|docId> --json",
     output: "json",
     mutates: true,
@@ -11420,82 +10947,12 @@ var AGENT_COMMANDS = [
   },
   {
     name: "state",
-    summary: "Return full merged Markdown and sidecar state for one document.",
+    summary: "Return clean Markdown document state for one document.",
     usage: "mdocs state <path|docId> --json",
     output: "json",
     mutates: true,
     examples: ["mdocs state docs/example.md --json"]
   },
-  {
-    name: "comment",
-    summary: "Create a sidecar comment without modifying clean Markdown.",
-    usage: "mdocs comment <path|docId> --range <start:end> --body <text> --json",
-    output: "json",
-    mutates: true,
-    examples: [
-      'mdocs comment docs/example.md --range 3:5 --body "Check this claim." --json',
-      'mdocs comment docs/example.md --range 3:5 --body-file /tmp/comment.txt --actor agent_local --actor-kind agent --actor-name "Local Agent" --json'
-    ],
-    notes: ["--range is 1-based and inclusive, validated against the current document line count."]
-  },
-  {
-    name: "suggest",
-    summary: "Create a reviewMarkdown replacement suggestion without modifying canonical Markdown.",
-    usage: "mdocs suggest <path|docId> --range <start:end> --with <markdown> --message <text> --json",
-    output: "json",
-    mutates: true,
-    examples: [
-      'mdocs suggest docs/example.md --range 4:4 --with "Better line." --message "Tighten wording." --json',
-      'mdocs suggest docs/example.md --range 4:9 --with-file /tmp/replacement.md --message-file /tmp/message.txt --actor agent_local --actor-kind agent --actor-name "Local Agent" --json'
-    ],
-    notes: [
-      "--range is 1-based and inclusive, validated against the current document line count.",
-      "The replacement text replaces the whole range; re-read context first so the range matches current content.",
-      "Prefer the smallest coherent range for the intended revision. If only one sentence inside a line changes, keep the rest of that line identical; use longer ranges only when the broader rewrite is genuinely needed."
-    ]
-  },
-  {
-    name: "comments",
-    summary: "List all comment threads for a document.",
-    usage: "mdocs comments <path|docId> --json",
-    output: "json",
-    mutates: true,
-    examples: ["mdocs comments docs/example.md --json"]
-  },
-  {
-    name: "suggestions",
-    summary: "List all suggestions for a document.",
-    usage: "mdocs suggestions <path|docId> --json",
-    output: "json",
-    mutates: true,
-    examples: ["mdocs suggestions docs/example.md --json"]
-  },
-  {
-    name: "accept",
-    summary: "Apply and accept an existing suggestion.",
-    usage: "mdocs accept <suggestionId> --json",
-    output: "json",
-    mutates: true,
-    examples: ["mdocs accept suggestion_abc123 --json"],
-    notes: ["Only use when the user explicitly asks to apply a suggestion."]
-  },
-  {
-    name: "reject",
-    summary: "Reject an existing suggestion.",
-    usage: "mdocs reject <suggestionId> --json",
-    output: "json",
-    mutates: true,
-    examples: ["mdocs reject suggestion_abc123 --json"],
-    notes: ["Only use when the user explicitly asks to reject a suggestion."]
-  },
-  {
-    name: "resolve-comment",
-    summary: "Resolve an existing comment thread.",
-    usage: "mdocs resolve-comment <commentId> --json",
-    output: "json",
-    mutates: true,
-    examples: ["mdocs resolve-comment comment_abc123 --json"]
-  },
   {
     name: "status",
     summary: "Return local Git status plus the Magic Markdown workspace map.",
@@ -11626,14 +11083,14 @@ function getAgentGuidePayload() {
 function getAgentSkillMarkdown() {
   return `---
 name: magic-markdown
-description: Use the Magic Markdown CLI or MCP server to read, organize, review, comment on, suggest edits to, and sync clean Markdown workspaces without hand-editing .mdocs sidecars. Use when an agent needs to interact with Magic Markdown documents, library folders, comments, suggestions, image context, checkpoints, or local source sync.
+description: Use the Magic Markdown CLI or MCP server to read clean Markdown workspaces, and use remote authority commands for comments, suggestions, accept, and reject. Use when an agent needs to interact with Magic Markdown documents, library folders, image context, checkpoints, remote review state, or local source sync.
 metadata:
   short-description: Operate Magic Markdown via CLI/MCP
 ---
 
 # Magic Markdown Agent Workflow
 
-Magic Markdown keeps Markdown files clean and stores collaboration metadata in .mdocs sidecars. Treat .mdocs as an implementation detail: use the CLI or MCP resources/tools instead of reading or editing sidecar JSON by hand.
+Magic Markdown keeps Markdown files clean. Review state lives in DocumentAuthority: comments, suggestions, accept, and reject must use \`mdocs remote ...\` or the remote MCP connector, not local \`.mdocs\` files.
 
 ## Install / Bootstrap
 
@@ -11653,7 +11110,7 @@ Run \`mdocs help <command>\` (or \`mdocs <command> --help\`) for usage, examples
 4. Run \`mdocs map --json\` or \`mdocs remote map --json\` to list documents, paths, docIds, open comments, open suggestions, anchor review counts, and link counts. File-scoped joins (most share links) cover a single document, so \`mdocs remote map\` is unavailable for them \u2014 use \`mdocs remote context --summary --json\` instead. Project-scoped joins cover one root; workspace-scoped joins cover Home and can target duplicate paths as \`<rootId>:<path-or-docId>\`.
 5. Run \`mdocs graph --json\` or project-scoped \`mdocs remote graph --json\` before broad edits to inspect the Obsidian-style document graph built from Markdown links and wikilinks.
 6. For a document, run \`mdocs context <path|docId> --summary --json\` locally or \`mdocs remote context <path|docId> --summary --json\` for a joined share before reading full content. Then page Markdown with \`--start-line\` / \`--end-line\` and \`--no-review\` when you only need document text.
-7. Pull review state separately with \`mdocs review <path|docId> --json\` locally or \`mdocs remote review <path|docId> --json\` for a joined share. Use \`mdocs comment\` / \`mdocs remote comment\` for review notes and \`mdocs suggest\` / \`mdocs remote suggest\` for proposed replacements. Do not hand-edit canonical Markdown files or \`.mdocs\` reviewMarkdown syntax directly.
+7. Pull review state separately with \`mdocs review <path|docId> --json\` locally or \`mdocs remote review <path|docId> --json\` for a joined share. Use \`mdocs comment\` / \`mdocs remote comment\` for review notes and \`mdocs suggest\` / \`mdocs remote suggest\` for proposed replacements. Do not hand-edit canonical Markdown files or local review metadata directly.
 
 ## Filesystem Bridge / Resume
 
@@ -11693,7 +11150,7 @@ If Magic and the local root both changed the same document while you were offlin
 
 ## Editing Rules
 
-- Comments are sidecar operations; suggestions are reviewMarkdown operations derived into sidecar state. They should not modify canonical Markdown until a suggestion is accepted.
+- Comments and suggestions are review operations. They should not modify canonical Markdown until a suggestion is accepted through authority.
 - \`--range <start:end>\` is 1-based and inclusive, and validated against the current document: read the document first and quote line numbers from what you just read.
 - Prefer the smallest coherent suggestion range that contains the actual change. If one sentence, list item, table row, or short paragraph changes, suggest that unit rather than replacing surrounding unchanged paragraphs or sections.
 - Broader paragraph, section, or multi-section rewrites are appropriate when the edit genuinely changes structure, ordering, transitions, or multiple interdependent ideas. Do not avoid a long edit when it is the clearest correct revision.
@@ -11878,14 +11335,14 @@ async function runDoctor(io, workspaceRoot) {
       details: `${map.docs.length} Markdown document${map.docs.length === 1 ? "" : "s"} indexed.`
     },
     {
-      name: "sidecar_anchor_mapping",
+      name: "authority_projection_mapping",
       ok: warnings.length === 0,
-      details: warnings.length === 0 ? "All sidecar anchors are mapped." : `${warnings.length} document(s) have anchors needing review.`
+      details: warnings.length === 0 ? "No authority projection mapping warnings." : `${warnings.length} document(s) have review targets needing projection attention.`
     },
     {
       name: "agent_cli_contract",
       ok: AGENT_COMMANDS.length > 0,
-      details: "Agent guide, JSON commands, checkpoints, document context, suggestions, comments, and MCP stdio are available."
+      details: "Agent guide, JSON commands, checkpoints, clean document context, and MCP stdio are available. Review mutations require remote authority commands."
     }
   ];
   return {
@@ -11947,6 +11404,14 @@ var NodeWorkspaceIO = class {
       return false;
     }
   }
+  async statFile(path) {
+    try {
+      const stats = await stat2(await this.resolveExistingPath(path));
+      return { mtimeMs: stats.mtimeMs, size: stats.size };
+    } catch {
+      return void 0;
+    }
+  }
   async mkdir(path) {
     const target = await this.resolvePath(path);
     await mkdir2(target, { recursive: true });
@@ -12001,6 +11466,9 @@ var PathMappedWorkspaceIO = class {
   async exists(path) {
     return this.local.exists(this.toReplicaPath(path));
   }
+  async statFile(path) {
+    return this.local.statFile(this.toReplicaPath(path));
+  }
   async mkdir(path) {
     await this.local.mkdir(this.toReplicaPath(path));
   }
@@ -12098,28 +11566,6 @@ function optionalString(args, name) {
   const value = args[name];
   return typeof value === "string" ? value : void 0;
 }
-function requiredNumber(args, name) {
-  const value = args[name];
-  const number = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
-  if (!Number.isFinite(number)) throw new Error(`Missing numeric tool argument: ${name}`);
-  return number;
-}
-function actorFromArgs(args, fallback) {
-  const id = optionalString(args, "actorId") ?? fallback.id;
-  const name = optionalString(args, "actorName") ?? fallback.name;
-  const email = optionalString(args, "actorEmail") ?? fallback.email;
-  const kind = actorKindFromArg(args.actorKind) ?? fallback.kind;
-  return {
-    id,
-    kind,
-    name,
-    ...email ? { email } : {}
-  };
-}
-function actorKindFromArg(value) {
-  if (value === "human" || value === "agent" || value === "system") return value;
-  return void 0;
-}
 
 // src/mcp-resources.ts
 import { readFile as readFile3 } from "node:fs/promises";
@@ -12180,19 +11626,12 @@ async function contextForDocument(io, path, startLine, endLine, options = {}) {
     markdown,
     images: withMcpImageResources(io, state).images,
     links: state.links,
-    ...options.includeReview === false ? {} : reviewFields(state)
+    ...options.includeReview === false ? {} : { review: reviewStateForDocument(state) }
   };
 }
 async function reviewForDocument(io, path) {
   return reviewStateForDocument(await getDocumentState(io, path));
 }
-function reviewFields(state) {
-  return {
-    comments: state.sidecar.comments.filter((comment2) => comment2.status === "open"),
-    suggestions: state.sidecar.suggestions.filter((suggestion) => suggestion.status === "open"),
-    anchors: state.anchors
-  };
-}
 function imageResourceUri(docId, index) {
   return `mdocs://documents/${docId}/images/${index}`;
 }
@@ -12233,25 +11672,6 @@ var documentPathSchema = {
   required: ["path"],
   additionalProperties: false
 };
-var actorProperties = {
-  actorId: {
-    type: "string",
-    description: "Optional actor id to record in sidecar metadata."
-  },
-  actorName: {
-    type: "string",
-    description: "Optional actor display name to record in sidecar metadata."
-  },
-  actorKind: {
-    type: "string",
-    enum: ["human", "agent", "system"],
-    description: "Optional actor kind to record in sidecar metadata."
-  },
-  actorEmail: {
-    type: "string",
-    description: "Optional actor email to record in sidecar metadata."
-  }
-};
 var tools = [
   {
     name: "mdocs_map",
@@ -12270,101 +11690,41 @@ var tools = [
   },
   {
     name: "mdocs_context",
-    description: "Return agent-ready document Markdown and resolved outgoing links. Use summary=true first to inspect title, line count, headings, current head, and review/link/image counts without dumping the full document. Use includeReview=false when reading content only, and mdocs_review for comments, suggestions, and anchors.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        path: documentPathSchema.properties.path,
-        startLine: {
-          type: "number",
-          description: "1-based first line to include (default: 1). The response startLine/endLine/totalLines fields tell you what was returned and whether more pages exist."
-        },
-        endLine: {
-          type: "number",
-          description: "1-based last line to include (default: last line of document)."
-        },
-        summary: {
-          type: "boolean",
-          description: "Return metadata, heading outline, current head, and counts instead of Markdown content."
-        },
-        includeReview: {
-          type: "boolean",
-          description: "Whether to include open comments, suggestions, and anchors in the content response (default: true). Use false to keep document reading separate from review state."
-        }
-      },
-      required: ["path"],
-      additionalProperties: false
-    }
-  },
-  {
-    name: "mdocs_review",
-    description: "Return open comments, open suggestions, and mapped anchors for one document without returning document Markdown.",
-    inputSchema: documentPathSchema
-  },
-  {
-    name: "mdocs_state",
-    description: "Return full merged Markdown and sidecar state for one document.",
-    inputSchema: documentPathSchema
-  },
-  {
-    name: "mdocs_comment",
-    description: "Create a sidecar comment without modifying clean Markdown.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        path: documentPathSchema.properties.path,
-        startLine: { type: "number", description: "1-based start line." },
-        endLine: { type: "number", description: "1-based end line." },
-        body: { type: "string", description: "Comment body." },
-        ...actorProperties
-      },
-      required: ["path", "startLine", "endLine", "body"],
-      additionalProperties: false
-    }
-  },
-  {
-    name: "mdocs_suggest",
-    description: "Create a reviewMarkdown replacement suggestion without modifying canonical Markdown. Prefer the smallest coherent range; use longer ranges only when the broader rewrite is genuinely needed.",
+    description: "Return agent-ready clean Markdown and resolved outgoing links. Use summary=true first to inspect title, line count, headings, current head, and review/link/image counts without dumping the full document. Review mutations require the remote MCP connector or mdocs remote commands.",
     inputSchema: {
       type: "object",
       properties: {
         path: documentPathSchema.properties.path,
-        startLine: { type: "number", description: "1-based start line." },
-        endLine: { type: "number", description: "1-based end line." },
-        replacement: { type: "string", description: "Exact replacement Markdown for the line range; keep unchanged surrounding text identical for narrow edits." },
-        message: { type: "string", description: "Short explanation for the suggestion." },
-        ...actorProperties
+        startLine: {
+          type: "number",
+          description: "1-based first line to include (default: 1). The response startLine/endLine/totalLines fields tell you what was returned and whether more pages exist."
+        },
+        endLine: {
+          type: "number",
+          description: "1-based last line to include (default: last line of document)."
+        },
+        summary: {
+          type: "boolean",
+          description: "Return metadata, heading outline, current head, and counts instead of Markdown content."
+        },
+        includeReview: {
+          type: "boolean",
+          description: "Whether to include authority-review redirect metadata in the content response (default: true). Use false to keep document reads minimal."
+        }
       },
-      required: ["path", "startLine", "endLine", "replacement"],
+      required: ["path"],
       additionalProperties: false
     }
   },
   {
-    name: "mdocs_resolve_comment",
-    description: "Resolve a sidecar comment thread.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        commentId: { type: "string", description: "Comment thread id." },
-        ...actorProperties
-      },
-      required: ["commentId"],
-      additionalProperties: false
-    }
+    name: "mdocs_review",
+    description: "Return local review redirect metadata for one document. Use remote MCP or mdocs remote review for authority-backed comments and suggestions.",
+    inputSchema: documentPathSchema
   },
   {
-    name: "mdocs_resolve_suggestion",
-    description: "Accept or reject a suggestion.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        suggestionId: { type: "string", description: "Suggestion id." },
-        status: { type: "string", enum: ["accepted", "rejected"], description: "Resolution status." },
-        ...actorProperties
-      },
-      required: ["suggestionId", "status"],
-      additionalProperties: false
-    }
+    name: "mdocs_state",
+    description: "Return clean Markdown document state and metadata for one document.",
+    inputSchema: documentPathSchema
   },
   {
     name: "mdocs_diff",
@@ -12560,38 +11920,8 @@ async function callTool(io, name, args) {
   }
   if (name === "mdocs_review") return reviewForDocument(io, requiredString(args, "path"));
   if (name === "mdocs_state") return withMcpImageResources(io, await getDocumentState(io, requiredString(args, "path")));
-  if (name === "mdocs_comment") {
-    return addComment(
-      io,
-      requiredString(args, "path"),
-      { startLine: requiredNumber(args, "startLine"), endLine: requiredNumber(args, "endLine") },
-      requiredString(args, "body"),
-      actorFromArgs(args, defaultActor())
-    );
-  }
-  if (name === "mdocs_suggest") {
-    return addSuggestion(
-      io,
-      requiredString(args, "path"),
-      { startLine: requiredNumber(args, "startLine"), endLine: requiredNumber(args, "endLine") },
-      requiredString(args, "replacement"),
-      optionalString(args, "message") ?? "Suggested edit",
-      actorFromArgs(args, {
-        id: "agent_local",
-        kind: "agent",
-        name: "Local Agent"
-      })
-    );
-  }
-  if (name === "mdocs_resolve_suggestion") {
-    const suggestionId = requiredString(args, "suggestionId");
-    const status = requiredString(args, "status");
-    if (status === "accepted") return acceptSuggestion(io, suggestionId, actorFromArgs(args, defaultActor()));
-    if (status === "rejected") return rejectSuggestion(io, suggestionId, actorFromArgs(args, defaultActor()));
-    throw new Error("status must be accepted or rejected");
-  }
-  if (name === "mdocs_resolve_comment") {
-    return resolveComment(io, requiredString(args, "commentId"), actorFromArgs(args, defaultActor()));
+  if (name === "mdocs_comment" || name === "mdocs_suggest" || name === "mdocs_resolve_suggestion" || name === "mdocs_resolve_comment") {
+    throw new Error("Local MCP review mutations were removed. Use the remote MCP connector or `mdocs remote ...` so review state goes through DocumentAuthority.");
   }
   if (name === "mdocs_diff") {
     return { patch: await gitDiff(io.root, optionalString(args, "path")) };
@@ -12802,33 +12132,47 @@ function splitWorkspaceDocumentTarget(value, rootIds) {
   const target = value.slice(separator + 1);
   return target ? { rootId, target } : void 0;
 }
-async function postReview(record, docId, additions, actor) {
-  const response = await fetchJson(
-    `${record.origin}/api/workspaces/${encodeURIComponent(record.workspaceId)}/roots/${encodeURIComponent(record.rootId)}/documents/${encodeURIComponent(docId)}/review`,
+async function postSuggestionBranch(record, docId, input, actor) {
+  return fetchJson(
+    `${record.origin}/api/workspaces/${encodeURIComponent(record.workspaceId)}/roots/${encodeURIComponent(record.rootId)}/documents/${encodeURIComponent(docId)}/suggestions`,
+    {
+      method: "POST",
+      headers: { ...shareHeaders(record.shareUrl), "Content-Type": "application/json" },
+      body: JSON.stringify({ actor, ...input })
+    }
+  );
+}
+async function fetchAuthorityState(record, docId) {
+  return fetchJson(
+    `${record.origin}/api/workspaces/${encodeURIComponent(record.workspaceId)}/roots/${encodeURIComponent(record.rootId)}/documents/${encodeURIComponent(docId)}/authority-state`,
+    { headers: shareHeaders(record.shareUrl) }
+  );
+}
+async function postResolveSuggestionBranch(record, docId, suggestionId, resolution, actor, changeId = randomUUID2()) {
+  return fetchJson(
+    `${record.origin}/api/workspaces/${encodeURIComponent(record.workspaceId)}/roots/${encodeURIComponent(record.rootId)}/documents/${encodeURIComponent(docId)}/suggestions/${encodeURIComponent(suggestionId)}/${resolution}`,
     {
       method: "POST",
       headers: { ...shareHeaders(record.shareUrl), "Content-Type": "application/json" },
-      body: JSON.stringify({ actor, changeId: randomUUID2(), ...additions })
+      body: JSON.stringify({ actor, changeId })
     }
   );
-  return response.document;
 }
-async function postReviewOperation(record, docId, operation, actor) {
+async function postAuthorityComment(record, docId, input, actor) {
   return fetchJson(
-    `${record.origin}/api/workspaces/${encodeURIComponent(record.workspaceId)}/roots/${encodeURIComponent(record.rootId)}/documents/${encodeURIComponent(docId)}/review-ops`,
+    `${record.origin}/api/workspaces/${encodeURIComponent(record.workspaceId)}/roots/${encodeURIComponent(record.rootId)}/documents/${encodeURIComponent(docId)}/comments`,
     {
       method: "POST",
       headers: { ...shareHeaders(record.shareUrl), "Content-Type": "application/json" },
-      body: JSON.stringify({ actor, operation })
+      body: JSON.stringify({ actor, ...input })
     }
   );
 }
-async function pushDocument(record, baseDocument, markdown, sidecar) {
+async function pushDocument(record, baseDocument, markdown) {
   const createdAt = (/* @__PURE__ */ new Date()).toISOString();
   const payload = {
     ...baseDocument,
     markdown,
-    sidecar,
     baseHead: baseDocument.currentSha,
     currentSha: baseDocument.currentSha
   };
@@ -13081,6 +12425,7 @@ function joinStoreDir(root) {
 }
 
 // src/remote.ts
+var WORKSPACE_GRAPH_SCHEMA_VERSION = 1;
 async function runJoinCommand(root, parsed) {
   const target = parsed.command[1];
   const existingId = typeof parsed.flags.id === "string" ? parsed.flags.id : void 0;
@@ -13131,7 +12476,7 @@ async function runRemoteCommand(root, subcommand, parsed) {
       if (record.scope === "workspace") return remoteWorkspaceMap(record);
       const rootRecord = assertRootScoped(record, "map");
       await refreshPresence(rootRecord, record.docId);
-      return fetchTree(rootRecord);
+      return treeWithAuthorityCounts(rootRecord, await fetchTree(rootRecord));
     }
     case "graph":
       return remoteGraph(record);
@@ -13225,28 +12570,35 @@ async function remoteGraph(record) {
   assertProjectScope(record, "graph");
   const rootRecord = assertRootScoped(record, "graph");
   await refreshPresence(rootRecord, record.docId);
-  const tree = await fetchTree(rootRecord);
+  const tree = await treeWithAuthorityCounts(rootRecord, await fetchTree(rootRecord));
   const documents = await Promise.all(tree.docs.map((doc) => fetchDocument(rootScopedRecordFor(record, rootRecord.rootId), doc.docId)));
+  const authorityCounts = new Map(tree.docs.map((doc) => [doc.docId, doc]));
   const lookup = documents.map((doc) => ({ docId: doc.docId, path: doc.path, title: doc.title }));
   const graphDocuments = documents.map((doc) => {
     const links = doc.links ?? resolveMarkdownLinks(extractMarkdownLinks(doc.markdown), doc, lookup);
+    const counts = authorityCounts.get(doc.docId);
     return {
       docId: doc.docId,
       path: doc.path,
       title: doc.title,
-      openComments: doc.openComments,
-      openSuggestions: doc.openSuggestions,
-      anchorsNeedingReview: doc.anchors.filter((anchor) => anchor.status !== "mapped").length,
+      openComments: counts?.openComments ?? 0,
+      openSuggestions: counts?.openSuggestions ?? 0,
+      anchorsNeedingReview: counts?.anchorsNeedingReview ?? 0,
       externalLinks: links.filter((link2) => link2.status === "external").length,
       unresolvedLinks: links.filter((link2) => link2.status === "unresolved" || link2.status === "ambiguous").length,
       links
     };
   });
-  return buildWorkspaceGraph(record.workspaceId, SIDECAR_SCHEMA_VERSION, graphDocuments);
+  return buildWorkspaceGraph(record.workspaceId, WORKSPACE_GRAPH_SCHEMA_VERSION, graphDocuments);
 }
 async function remoteWorkspaceMap(record) {
   const roots = await fetchWorkspaceRoots(record);
-  const trees = await Promise.all(roots.map((root) => fetchTree(rootScopedRecordFor(record, root.rootId))));
+  const trees = await Promise.all(
+    roots.map(async (root) => {
+      const rootRecord = rootScopedRecordFor(record, root.rootId);
+      return treeWithAuthorityCounts(rootRecord, await fetchTree(rootRecord));
+    })
+  );
   const library = await fetchWorkspaceLibrary(record).catch(() => void 0);
   return {
     workspaceId: record.workspaceId,
@@ -13270,6 +12622,27 @@ async function remoteWorkspaceMap(record) {
     ...library ? { folders: library.folders } : {}
   };
 }
+async function treeWithAuthorityCounts(record, tree) {
+  const counts = await Promise.all(
+    tree.docs.map(async (doc) => ({
+      docId: doc.docId,
+      counts: authorityReviewCounts(await fetchAuthorityState(record, doc.docId).catch(() => void 0))
+    }))
+  );
+  const countsByDocId = new Map(counts.map((entry) => [entry.docId, entry.counts]));
+  return {
+    ...tree,
+    docs: tree.docs.map((doc) => {
+      const review = countsByDocId.get(doc.docId);
+      return review ? {
+        ...doc,
+        openComments: review.openComments,
+        openSuggestions: review.openSuggestions,
+        anchorsNeedingReview: review.anchorsNeedingReview
+      } : doc;
+    })
+  };
+}
 async function remoteHistory(record, flags) {
   const rootRecord = assertRootScoped(record, "history");
   await refreshPresence(rootRecord, record.docId);
@@ -13329,9 +12702,11 @@ async function refreshPresence(record, docId) {
 }
 async function remoteContext(record, pathOrDocId, flags = {}) {
   const document = pathOrDocId ? await fetchDocument(record, pathOrDocId) : (await fetchState(record)).document;
-  await refreshPresence(rootScopedRecordFor(record, document.rootId), document.docId);
+  const rootRecord = rootScopedRecordFor(record, document.rootId);
+  await refreshPresence(rootRecord, document.docId);
+  const authority = flags["no-review"] ? void 0 : await fetchAuthorityState(rootRecord, document.docId).catch(() => void 0);
   if (flags.summary || flags["metadata-only"]) {
-    return withRemoteSummaryNextCommands(summarizeDocumentContext(document), record, document, pathOrDocId);
+    return withRemoteSummaryNextCommands(summarizeDocumentContextFromAuthority(document, authority), record, document, pathOrDocId);
   }
   const startLine = typeof flags["start-line"] === "string" ? Number(flags["start-line"]) : void 0;
   const endLine = typeof flags["end-line"] === "string" ? Number(flags["end-line"]) : void 0;
@@ -13347,22 +12722,24 @@ async function remoteContext(record, pathOrDocId, flags = {}) {
     startLine: sl,
     endLine: el,
     markdown,
-    ...flags["no-review"] ? {} : {
-      comments: document.sidecar.comments.filter((comment2) => comment2.status === "open"),
-      suggestions: document.sidecar.suggestions.filter((suggestion) => suggestion.status === "open"),
-      anchors: document.anchors
-    },
+    ...flags["no-review"] ? {} : authorityReviewPayload(authority),
     images: document.images,
     links: document.links
   };
 }
 async function remoteReview(record, pathOrDocId) {
   const document = pathOrDocId ? await fetchDocument(record, pathOrDocId) : (await fetchState(record)).document;
-  await refreshPresence(rootScopedRecordFor(record, document.rootId), document.docId);
+  const rootRecord = rootScopedRecordFor(record, document.rootId);
+  await refreshPresence(rootRecord, document.docId);
+  const authority = await fetchAuthorityState(rootRecord, document.docId).catch(() => void 0);
   return {
     joinId: record.joinId,
     scope: record.scope,
-    ...reviewStateForDocument(document)
+    docId: document.docId,
+    path: document.path,
+    title: document.title,
+    currentSha: document.currentSha,
+    ...authorityReviewPayload(authority)
   };
 }
 function withRemoteSummaryNextCommands(summary, record, document, requestedTarget) {
@@ -13382,6 +12759,48 @@ function remoteCommandTarget(record, document, requestedTarget) {
   if (record.scope === "workspace") return ` ${document.rootId}:${document.docId}`;
   return ` ${document.docId}`;
 }
+function summarizeDocumentContextFromAuthority(document, authority) {
+  const summary = summarizeDocumentContext(document);
+  return {
+    ...summary,
+    reviewCounts: authorityReviewCounts(authority)
+  };
+}
+function authorityReviewPayload(authority) {
+  return {
+    comments: authorityOpenComments(authority),
+    suggestions: authorityOpenSuggestions(authority),
+    commentTargets: authority?.commentProjections ?? []
+  };
+}
+function authorityReviewCounts(authority) {
+  const suggestions = authorityOpenSuggestions(authority);
+  const comments = authorityOpenComments(authority);
+  return {
+    openComments: comments.length,
+    openSuggestions: suggestions.length,
+    anchorsNeedingReview: (authority?.commentProjections ?? []).filter((projection) => authorityRecordStatus(projection) !== "mapped").length + suggestions.filter((suggestion) => {
+      const projection = suggestion && typeof suggestion === "object" ? suggestion.projection : void 0;
+      const status = authorityRecordStatus(projection);
+      return status === "conflicted" || status === "stale";
+    }).length
+  };
+}
+function authorityOpenComments(authority) {
+  return (authority?.comments ?? []).filter((comment2) => {
+    const status = authorityRecordStatus(comment2);
+    return status === void 0 || status === "open" || status === "displaced";
+  });
+}
+function authorityOpenSuggestions(authority) {
+  return (authority?.suggestions ?? []).filter((suggestion) => authorityRecordStatus(suggestion) === "open");
+}
+function authorityRecordId(value) {
+  return value && typeof value === "object" && typeof value.id === "string" ? value.id : void 0;
+}
+function authorityRecordStatus(value) {
+  return value && typeof value === "object" && typeof value.status === "string" ? value.status : void 0;
+}
 async function remoteCreateFile(root, record, parsed) {
   assertProjectScope(record, "create-file");
   const rootRecord = assertRootScoped(record, "create-file");
@@ -13402,7 +12821,7 @@ async function remoteCreateFile(root, record, parsed) {
   }
   const docId = createDocId();
   const title = titleFromMarkdown(normalizedPath, markdown);
-  const sidecar = emptySidecar(docId, normalizedPath, title);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
   const baseDocument = {
     workspaceId: rootRecord.workspaceId,
     rootId: rootRecord.rootId,
@@ -13410,16 +12829,15 @@ async function remoteCreateFile(root, record, parsed) {
     path: normalizedPath,
     title,
     markdown,
-    reviewMarkdown: markdown,
-    sidecar,
-    anchors: [],
     images: [],
     links: [],
     openComments: 0,
     openSuggestions: 0,
+    anchorsNeedingReview: 0,
+    updatedAt: now,
     currentSha: tree.root.canonical.head
   };
-  const document = await pushDocument(rootRecord, baseDocument, markdown, sidecar);
+  const document = await pushDocument(rootRecord, baseDocument, markdown);
   await recordHead(root, record, document);
   return { document };
 }
@@ -13444,8 +12862,7 @@ async function remoteMoveFile(root, record, parsed) {
   const moved = await pushDocument(
     rootScopedRecordFor(record, document.rootId),
     { ...document, path: nextPath, title: titleFromMarkdown(nextPath, document.markdown) },
-    document.markdown,
-    document.sidecar
+    document.markdown
   );
   await recordHead(root, record, moved);
   return { document: moved };
@@ -13453,13 +12870,17 @@ async function remoteMoveFile(root, record, parsed) {
 async function remoteComment(root, record, parsed) {
   const body = await readRequiredTextFlag(parsed.flags, root, ["body", "message"]);
   const range = parseRange(requiredFlag(parsed.flags, "range"));
-  const result = await submitReview(
-    root,
-    record,
-    parsed.command[2] ?? record.docId,
-    (io, docId) => addComment(io, docId, range, body, actorForRecord(record))
-  );
-  return { comment: result.created, document: result.document };
+  const pathOrDocId = parsed.command[2] ?? record.docId;
+  if (!pathOrDocId) {
+    throw new CliError("usage_error", "Missing document path or docId.", {
+      hint: "Pass a document path or docId, or join with --doc <docId>."
+    });
+  }
+  const document = await fetchDocument(record, pathOrDocId);
+  const documentRecord = rootScopedRecordFor(record, document.rootId);
+  await refreshPresence(documentRecord, document.docId);
+  const result = await postAuthorityComment(documentRecord, document.docId, { ...range, body }, actorForRecord(record));
+  return { comment: result.thread, projection: result.projection, document: { docId: document.docId, path: document.path, currentSha: document.currentSha } };
 }
 async function remoteSuggest(root, record, parsed) {
   const replacement = await readRequiredTextFlag(parsed.flags, root, ["with", "replacement"]);
@@ -13474,15 +12895,35 @@ async function remoteSuggest(root, record, parsed) {
   const document = await fetchDocument(record, pathOrDocId);
   const documentRecord = rootScopedRecordFor(record, document.rootId);
   await refreshPresence(documentRecord, document.docId);
-  const result = await postReviewOperation(
+  const authority = await fetchAuthorityState(documentRecord, document.docId);
+  if (!authority.head) {
+    throw new CliError("conflict", "Document authority is not initialized yet.", {
+      hint: "Open the document once or retry after the worker initializes authority-state."
+    });
+  }
+  const clientMutationId = typeof parsed.flags["client-mutation-id"] === "string" ? parsed.flags["client-mutation-id"] : typeof parsed.flags["mutation-id"] === "string" ? parsed.flags["mutation-id"] : void 0;
+  const patch = buildLineRangePatchEnvelope({
+    baseVersion: authority.head.headVersion,
+    base: authority.markdown ?? document.markdown,
+    range,
+    replacement,
+    clientMutationId,
+    clientMeta: { source: "cli_remote_suggest" }
+  });
+  const result = await postSuggestionBranch(
     documentRecord,
     document.docId,
-    { kind: "create_suggestion", baseHead: document.currentSha, payload: { ...range, replacement, message } },
+    { patch, title: message },
     actorForRecord(record)
   );
-  if (result.document) await recordHead(root, record, result.document);
-  const placementStatus = result.reviewRecord?.placement?.status;
-  return { suggestion: result.suggestion, reviewRecord: result.reviewRecord, placementStatus, projectionStatus: result.projectionStatus, document: result.document };
+  return {
+    suggestion: result.suggestion,
+    suggestionUpdate: result.update,
+    suggestionId: result.suggestion?.id,
+    projectionStatus: result.projection?.status,
+    replayed: result.replayed,
+    document: { docId: document.docId, path: document.path, currentSha: document.currentSha }
+  };
 }
 async function remoteCreateFolder(record, parsed) {
   assertProjectScope(record, "create-folder");
@@ -13561,53 +13002,14 @@ async function remoteReject(root, record, parsed) {
   let documentRecord = rootScopedRecordFor(record, document.rootId);
   await refreshPresence(documentRecord, document.docId);
   const actor = actorForRecord(record);
-  const suggestion = document.sidecar.suggestions.find((candidate) => candidate.id === suggestionId);
-  if (!suggestion) {
-    throw new CliError("not_found", `Unknown suggestion: ${suggestionId}`, {
-      hint: "List suggestion ids with mdocs remote review --json."
-    });
-  }
-  if (suggestion.status !== "open") {
-    throw new CliError("usage_error", `Suggestion ${suggestionId} is already ${suggestion.status}.`, {
+  const authority = await fetchAuthorityState(documentRecord, document.docId).catch(() => void 0);
+  const suggestionStatus = authorityRecordStatus(authority?.suggestions?.find((candidate) => authorityRecordId(candidate) === suggestionId));
+  if (suggestionStatus && suggestionStatus !== "open") {
+    throw new CliError("usage_error", `Suggestion ${suggestionId} is already ${suggestionStatus}.`, {
       hint: "Only open suggestions can be rejected."
     });
   }
-  const result = await postReviewOperation(
-    documentRecord,
-    document.docId,
-    { kind: "reject_suggestion", baseHead: document.currentSha, payload: { suggestionId } },
-    actor
-  );
-  if (result.document) await recordHead(root, record, result.document);
-  return { suggestion: result.suggestion ?? { ...suggestion, status: "rejected" }, reviewRecord: result.reviewRecord, document: result.document };
-}
-async function submitReview(root, record, pathOrDocId, mutate) {
-  if (!pathOrDocId) {
-    throw new CliError("usage_error", "Missing document path or docId.", {
-      hint: "Pass a document path or docId, or join with --doc <docId>."
-    });
-  }
-  let document = await fetchDocument(record, pathOrDocId);
-  let documentRecord = rootScopedRecordFor(record, document.rootId);
-  await refreshPresence(documentRecord, document.docId);
-  const build = async (base) => {
-    const io = new RemoteDocumentIO(base);
-    const created = await mutate(io, base.docId);
-    const state = await getDocumentState(io, base.docId);
-    return {
-      created,
-      state,
-      additions: {
-        anchors: state.sidecar.anchors.filter((anchor) => anchor.id === created.anchorId),
-        comments: state.sidecar.comments.filter((comment2) => comment2.id === created.id),
-        reviewMarkdown: state.sidecar.reviewMarkdown
-      }
-    };
-  };
-  const attempt = await build(document);
-  const pushed = await postReview(documentRecord, document.docId, attempt.additions, actorForRecord(record));
-  await recordHead(root, record, pushed);
-  return { created: attempt.created, document: pushed };
+  return postResolveSuggestionBranch(documentRecord, document.docId, suggestionId, "reject", actor);
 }
 async function recordHead(root, record, document) {
   await writeJoinRecord(root, { ...record, updatedAt: (/* @__PURE__ */ new Date()).toISOString(), currentHead: document.currentSha });
@@ -13737,19 +13139,6 @@ function rootScopedRecordFor(record, rootId) {
     scope: record.scope === "file" ? "file" : "project"
   };
 }
-function emptySidecar(docId, path, title) {
-  return {
-    schemaVersion: SIDECAR_SCHEMA_VERSION,
-    docId,
-    path,
-    title,
-    anchors: [],
-    comments: [],
-    suggestions: [],
-    changeSets: [],
-    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-  };
-}
 function defaultMarkdown(path) {
   return `# ${titleFromMarkdown(path, "")}
 `;
@@ -13780,13 +13169,54 @@ function optionalFolderTarget(value) {
 
 // src/bridge.ts
 import { createHash as createHash2, randomUUID as randomUUID3 } from "node:crypto";
-import { chmod, mkdir as mkdir4, readFile as readFile6, writeFile as writeFile4 } from "node:fs/promises";
+import { unlinkSync } from "node:fs";
+import { chmod, mkdir as mkdir4, readFile as readFile6, rm as rm3, writeFile as writeFile4 } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename as basename2, join as join4, resolve as resolve4 } from "node:path";
 var BRIDGE_CONFIG_PATH = ".mdocs/bridge.json";
 var BRIDGE_STATUS_PATH = ".mdocs/bridge-status.json";
+var BRIDGE_LOCK_PATH = ".mdocs/bridge.lock";
 var BRIDGE_HEARTBEAT_INTERVAL_MS = 1e4;
 var BRIDGE_TOKEN_STORE_PATH = join4(homedir(), ".mdocs", "bridge-tokens.json");
+var BRIDGE_MIN_INTERVAL_MS = 500;
+var BRIDGE_DEFAULT_INTERVAL_MS = 1e3;
+var BRIDGE_RECONNECT_BASE_MS = 1e3;
+var BRIDGE_RECONNECT_CAP_MS = 3e4;
+function createSerialQueue() {
+  let tail = Promise.resolve();
+  return (task) => {
+    const run = tail.then(task, task);
+    tail = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  };
+}
+function validateBridgeIntervalMs(raw) {
+  if (typeof raw === "boolean" || raw === void 0 || raw === null || raw === "") return BRIDGE_DEFAULT_INTERVAL_MS;
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value <= 0) return BRIDGE_DEFAULT_INTERVAL_MS;
+  return Math.max(BRIDGE_MIN_INTERVAL_MS, Math.floor(value));
+}
+function reconnectBackoffCeiling(attempt, baseMs = BRIDGE_RECONNECT_BASE_MS, capMs = BRIDGE_RECONNECT_CAP_MS) {
+  const exponent = Math.max(0, Math.floor(attempt));
+  return Math.min(capMs, baseMs * 2 ** exponent);
+}
+function reconnectDelayMs(attempt, baseMs = BRIDGE_RECONNECT_BASE_MS, capMs = BRIDGE_RECONNECT_CAP_MS, random = Math.random) {
+  return Math.floor(random() * (reconnectBackoffCeiling(attempt, baseMs, capMs) + 1));
+}
+function isConfirmingEcho(params) {
+  if (params.messageSourceId && params.messageSourceId === params.selfSourceId) return true;
+  return params.sentSignature !== void 0 && params.sentSignature === params.payloadSignature;
+}
+function shouldConflictCopyOnDelete(localSignature, baseSignature) {
+  return baseSignature === void 0 || localSignature !== baseSignature;
+}
+function conflictCopyStamp(date = /* @__PURE__ */ new Date(), entropy = randomUUID3().slice(0, 6)) {
+  const compact = date.toISOString().replaceAll(/[-:.]/g, "");
+  return `${compact.slice(0, 15)}-${entropy}`;
+}
 function bridgeSetupIdentity(input) {
   const actorName = input.actorName?.trim() || "Agent";
   return {
@@ -13874,21 +13304,33 @@ async function runBridge(options) {
   const pendingDocs = /* @__PURE__ */ new Set();
   const pendingDeletes = /* @__PURE__ */ new Set();
   const seenDocs = /* @__PURE__ */ new Set();
+  const sentSignatures = /* @__PURE__ */ new Map();
   const deniedSignatures = /* @__PURE__ */ new Map();
+  const indexCache = /* @__PURE__ */ new Map();
+  const indexOptions = { cache: indexCache, rootId };
+  const runManifest = createSerialQueue();
   let lastTreeSignature = "";
   const claimMode = Boolean(options.claimToken || localManifestSource?.canonicalHead);
   let lastAppliedHead = localManifestSource?.canonicalHead;
   let socket;
+  let pollTimer;
+  let reconnectTimer;
+  let ticking = false;
+  let reconnectAttempt = 0;
+  let suppressOpenResume = false;
+  let claimPrimed = false;
   let lastSuccessfulSyncAt;
   let lastHeartbeatAt;
   let lastHeartbeatSentMs = 0;
   let lastError;
+  const lock = await acquireBridgeLock(root);
   await writeCurrentBridgeStatus("starting");
   let token = options.token ?? await readStoredBridgeToken(options, rootId).catch(() => void 0);
   if (!token && options.resume && !options.requestToken) {
     const message = "Missing stored bridge token. Re-run mdocs bridge setup from a fresh Magic binding packet.";
     lastError = message;
     await writeCurrentBridgeStatus("error");
+    await lock.release();
     throw new Error(message);
   }
   if (!token && (options.claimToken || options.requestToken)) {
@@ -13899,6 +13341,7 @@ async function runBridge(options) {
     } catch (error) {
       lastError = errorMessage(error);
       await writeCurrentBridgeStatus("error");
+      await lock.release();
       throw error;
     }
   }
@@ -13908,6 +13351,7 @@ async function runBridge(options) {
   } catch (error) {
     lastError = errorMessage(error);
     await writeCurrentBridgeStatus("error");
+    await lock.release();
     throw error;
   }
   lastAppliedHead = lastAppliedHead ?? registeredRoot?.canonical.head;
@@ -13927,32 +13371,54 @@ async function runBridge(options) {
     updatedAt: (/* @__PURE__ */ new Date()).toISOString()
   });
   const backfilled = await resumeFromCanonical();
+  suppressOpenResume = true;
   if (options.once) {
     lastSuccessfulSyncAt = (/* @__PURE__ */ new Date()).toISOString();
     await writeCurrentBridgeStatus("once_complete");
+    await lock.release();
     return;
   }
+  if (claimMode && !backfilled) {
+    await primeLocalSignatures();
+    claimPrimed = true;
+  }
   connect();
-  if (claimMode && !backfilled) await primeLocalSignatures();
-  else await publishSnapshot("initial");
-  const timer = setInterval(() => {
-    void publishSnapshot("poll").catch((error) => {
-      lastError = errorMessage(error);
-      void writeCurrentBridgeStatus("error").catch(() => void 0);
-      sendHeartbeat("error", lastError);
-      process.stderr.write(`bridge poll failed: ${lastError}
-`);
-    });
-  }, options.intervalMs);
+  scheduleNextPoll();
   process.once("SIGINT", () => {
-    clearInterval(timer);
+    shutdownTimers();
     sendHeartbeat("offline", void 0, false);
     void writeCurrentBridgeStatus("stopped").catch(() => void 0).finally(() => {
       socket?.close();
-      process.exit(0);
+      void lock.release().finally(() => process.exit(0));
     });
   });
   await new Promise(() => void 0);
+  function shutdownTimers() {
+    if (pollTimer) clearTimeout(pollTimer);
+    if (reconnectTimer) clearTimeout(reconnectTimer);
+  }
+  function scheduleNextPoll() {
+    pollTimer = setTimeout(runPollTick, options.intervalMs);
+  }
+  async function runPollTick() {
+    if (ticking) {
+      scheduleNextPoll();
+      return;
+    }
+    ticking = true;
+    try {
+      await publishSnapshot("poll");
+    } catch (error) {
+      lastError = errorMessage(error);
+      void writeCurrentBridgeStatus("error").catch(() => void 0);
+      sendHeartbeat("error", lastError);
+      process.stderr.write(`bridge poll failed: ${lastError}
+`);
+    } finally {
+      ticking = false;
+      scheduleNextPoll();
+    }
+  }
   function connect() {
     const url = new URL(`/api/workspaces/${encodeURIComponent(options.workspaceId)}/roots/${encodeURIComponent(rootId)}/sync`, options.baseUrl);
     url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
@@ -13961,11 +13427,10 @@ async function runBridge(options) {
     if (token) url.searchParams.set("token", token);
     socket = new WebSocket(url);
     socket.addEventListener("open", () => {
-      lastError = void 0;
-      process.stdout.write(`mdocs bridge connected ${root} -> ${options.workspaceId}/${rootId}
+      void onSocketOpen().catch((error) => {
+        process.stderr.write(`bridge open handler failed: ${errorMessage(error)}
 `);
-      sendHeartbeat("synced");
-      void writeCurrentBridgeStatus("connected").catch(() => void 0);
+      });
     });
     socket.addEventListener("message", (event) => {
       if (typeof event.data !== "string") return;
@@ -13979,7 +13444,7 @@ async function runBridge(options) {
     socket.addEventListener("close", () => {
       socket = void 0;
       void writeCurrentBridgeStatus("offline").catch(() => void 0);
-      setTimeout(connect, 1e3);
+      scheduleReconnect();
     });
     socket.addEventListener("error", () => {
       lastError = "WebSocket error";
@@ -13987,8 +13452,34 @@ async function runBridge(options) {
       socket?.close();
     });
   }
+  function scheduleReconnect() {
+    const delayMs = reconnectDelayMs(reconnectAttempt);
+    reconnectAttempt += 1;
+    reconnectTimer = setTimeout(connect, delayMs);
+  }
+  async function onSocketOpen() {
+    lastError = void 0;
+    reconnectAttempt = 0;
+    process.stdout.write(`mdocs bridge connected ${root} -> ${options.workspaceId}/${rootId}
+`);
+    sendHeartbeat("synced");
+    void writeCurrentBridgeStatus("connected").catch(() => void 0);
+    pendingDocs.clear();
+    pendingDeletes.clear();
+    sentSignatures.clear();
+    lastTreeSignature = "";
+    if (suppressOpenResume) suppressOpenResume = false;
+    else await resumeFromCanonical();
+    await publishSnapshot("open");
+  }
+  function indexedMap() {
+    return runManifest(() => getWorkspaceMap(io, indexOptions));
+  }
+  function indexedDocState(pathOrDocId) {
+    return runManifest(() => getDocumentState(io, pathOrDocId, indexOptions));
+  }
   async function publishSnapshot(reason) {
-    const map = await getWorkspaceMap(io);
+    const map = await indexedMap();
     const currentDocIds = new Set(map.docs.map((doc) => doc.docId));
     const treeSignature = hashJson(map.docs.map((doc) => ({ docId: doc.docId, path: doc.path })));
     if (treeSignature !== lastTreeSignature) {
@@ -13997,19 +13488,21 @@ async function runBridge(options) {
       }
     }
     for (const doc of map.docs) {
-      const state = await getDocumentState(io, doc.docId);
+      const state = await indexedDocState(doc.docId);
       const payload = {
         ...state,
         workspaceId: options.workspaceId,
         rootId,
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
         currentSha: lastAppliedHead
       };
-      const signature = documentSignature(state.markdown, state.sidecar);
+      const signature = documentSignature(state.markdown);
       if (signatures.get(doc.docId) === signature || pendingDocs.has(doc.docId)) continue;
       if (deniedSignatures.get(doc.docId) === signature) continue;
       if (send("file-changed", { ...payload, baseHead: lastAppliedHead, replicaId })) {
         seenDocs.add(doc.docId);
         pendingDocs.add(doc.docId);
+        sentSignatures.set(doc.docId, signature);
       }
     }
     for (const docId of seenDocs) {
@@ -14055,10 +13548,10 @@ async function runBridge(options) {
     return true;
   }
   async function reconcileRemoteDocument(remote, base) {
-    const remoteSignature = documentSignature(remote.markdown, remote.sidecar);
-    const baseSignature = base ? documentSignature(base.markdown, base.sidecar) : void 0;
+    const remoteSignature = documentSignature(remote.markdown);
+    const baseSignature = base ? documentSignature(base.markdown) : void 0;
     const localState = await localStateForCanonical(remote);
-    const localSignature = localState ? documentSignature(localState.markdown, localState.sidecar) : void 0;
+    const localSignature = localState ? documentSignature(localState.markdown) : void 0;
     if (!localState) {
       await applyCanonicalDocument(remote);
       return "applied";
@@ -14086,24 +13579,37 @@ async function runBridge(options) {
     return "conflict";
   }
   async function reconcileRemoteDelete(docId, base) {
-    const localState = await getDocumentState(io, docId).catch(() => void 0);
-    if (!localState) return "noop";
-    const baseSignature = documentSignature(base.markdown, base.sidecar);
-    const localSignature = documentSignature(localState.markdown, localState.sidecar);
-    if (localSignature !== baseSignature) {
+    return applyCanonicalDelete(docId, base.path, documentSignature(base.markdown));
+  }
+  async function applyCanonicalDelete(docId, path, baseSignature) {
+    let localState = await indexedDocState(docId).catch(() => void 0);
+    if (!localState && path) {
+      const map = await indexedMap().catch(() => void 0);
+      const byPath = map?.docs.find((doc) => doc.path === path);
+      if (byPath) localState = await indexedDocState(byPath.docId).catch(() => void 0);
+    }
+    if (!localState) {
+      signatures.delete(docId);
+      seenDocs.delete(docId);
+      pendingDeletes.delete(docId);
+      return "noop";
+    }
+    const localSignature = documentSignature(localState.markdown);
+    const diverged = shouldConflictCopyOnDelete(localSignature, baseSignature);
+    if (diverged) {
       const copyPath = conflictCopyPath(localState.path);
       await io.writeTextAtomic(copyPath, localState.markdown);
-      await seedConflictCopySidecar(copyPath, localState);
+      await seedConflictCopyDocument(copyPath, localState.markdown);
       process.stderr.write(`local conflict ${localState.path}; local version saved as ${copyPath}, canonical delete applied
 `);
     }
     await io.deleteFile(localState.path).catch(() => void 0);
-    await io.deleteFile(sidecarPath(docId)).catch(() => void 0);
     await removeManifestDocument(docId, localState.path);
     signatures.delete(docId);
     seenDocs.delete(docId);
+    sentSignatures.delete(docId);
     pendingDeletes.delete(docId);
-    return localSignature === baseSignature ? "applied" : "conflict";
+    return diverged ? "conflict" : "applied";
   }
   async function handleIncoming(message) {
     if (message.type === "agent-unbound") {
@@ -14112,23 +13618,36 @@ async function runBridge(options) {
       if (!targetsUs) return;
       process.stdout.write(`mdocs bridge unbound by workspace; stopping ${root}
 `);
+      shutdownTimers();
       await writeCurrentBridgeStatus("stopped").catch(() => void 0);
       socket?.close();
+      await lock.release();
       process.exit(0);
     }
     if (message.type === "file-changed") {
-      await applyCanonicalDocument(readDocumentPayload(message.payload));
+      const payload = readDocumentPayload(message.payload);
+      const payloadSignature = documentSignature(payload.markdown);
+      if (isConfirmingEcho({
+        messageSourceId: message.sourceId,
+        selfSourceId: sourceId,
+        payloadSignature,
+        sentSignature: sentSignatures.get(payload.docId)
+      })) {
+        signatures.set(payload.docId, payloadSignature);
+        sentSignatures.delete(payload.docId);
+        pendingDocs.delete(payload.docId);
+        deniedSignatures.delete(payload.docId);
+        seenDocs.add(payload.docId);
+        lastAppliedHead = payload.canonicalHead ?? payload.currentSha ?? lastAppliedHead;
+        await writeSourceState(lastAppliedHead);
+        return;
+      }
+      await applyCanonicalDocument(payload);
     }
     if (message.type === "file-deleted") {
       const payload = message.payload;
       if (!payload.docId) return;
-      const map = await getWorkspaceMap(io);
-      const doc = map.docs.find((candidate) => candidate.docId === payload.docId);
-      if (doc) await io.deleteFile(doc.path);
-      await io.deleteFile(sidecarPath(payload.docId)).catch(() => void 0);
-      signatures.delete(payload.docId);
-      seenDocs.delete(payload.docId);
-      pendingDeletes.delete(payload.docId);
+      await applyCanonicalDelete(payload.docId, payload.path, signatures.get(payload.docId));
       lastAppliedHead = payload.canonicalHead ?? lastAppliedHead;
       await writeSourceState(lastAppliedHead);
       process.stdout.write(`applied canonical delete ${payload.docId} at ${lastAppliedHead ?? "unknown"}
@@ -14156,14 +13675,14 @@ async function runBridge(options) {
     }
   }
   async function applyCanonicalDocument(payload) {
-    const remoteSignature = documentSignature(payload.markdown, payload.sidecar);
+    const remoteSignature = documentSignature(payload.markdown);
     const localState = await localStateForCanonical(payload);
-    const localSignature = localState ? documentSignature(localState.markdown, localState.sidecar) : void 0;
+    const localSignature = localState ? documentSignature(localState.markdown) : void 0;
     if (localSignature && signatures.has(payload.docId) && localSignature !== signatures.get(payload.docId) && localSignature !== remoteSignature) {
       const copyPath = conflictCopyPath(payload.path);
       if (localState) {
         await io.writeTextAtomic(copyPath, localState.markdown);
-        await seedConflictCopySidecar(copyPath, localState);
+        await seedConflictCopyDocument(copyPath, localState.markdown);
       }
       send("conflict", {
         docId: payload.docId,
@@ -14180,21 +13699,13 @@ async function runBridge(options) {
       await io.deleteFile(localState.path).catch(() => void 0);
     }
     if (localState && localState.docId !== payload.docId) {
-      await io.deleteFile(sidecarPath(localState.docId)).catch(() => void 0);
       await removeManifestDocument(localState.docId, localState.path);
     }
     await io.writeTextAtomic(payload.path, payload.markdown);
-    await io.writeTextAtomic(sidecarPath(payload.docId), `${JSON.stringify(payload.sidecar, null, 2)}
-`);
-    const reviewMarkdown = projectReviewMarkdown(payload.markdown, payload.sidecar.suggestions);
-    if (reviewMarkdown === payload.markdown) {
-      await io.deleteFile(reviewFilePath(payload.path)).catch(() => void 0);
-    } else {
-      await io.writeTextAtomic(reviewFilePath(payload.path), reviewMarkdown);
-    }
     await upsertManifestDocument(payload);
     signatures.set(payload.docId, remoteSignature);
     deniedSignatures.delete(payload.docId);
+    sentSignatures.delete(payload.docId);
     seenDocs.add(payload.docId);
     pendingDocs.delete(payload.docId);
     lastAppliedHead = payload.canonicalHead ?? payload.currentSha ?? lastAppliedHead;
@@ -14202,38 +13713,33 @@ async function runBridge(options) {
     process.stdout.write(`applied canonical change ${payload.path} at ${lastAppliedHead ?? "unknown"}
 `);
   }
-  async function seedConflictCopySidecar(copyPath, state) {
-    const manifest = await readManifest(io).catch(() => void 0);
-    if (!manifest) return;
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    const docId = createDocId();
-    const title = titleFromMarkdown(copyPath, state.markdown);
-    const entry = {
-      docId,
-      path: copyPath,
-      title,
-      contentHash: contentHashForText(state.markdown),
-      updatedAt: now
-    };
-    await writeSidecar(io, {
-      ...state.sidecar,
-      docId,
-      path: copyPath,
-      title,
-      updatedAt: now
-    });
-    await writeManifest(io, {
-      ...manifest,
-      docs: [...manifest.docs.filter((doc) => doc.path !== copyPath && doc.docId !== docId), entry],
-      updatedAt: now
+  async function seedConflictCopyDocument(copyPath, markdown) {
+    await runManifest(async () => {
+      const manifest = await readManifest(io).catch(() => void 0);
+      if (!manifest) return;
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const docId = deterministicDocId(rootId, copyPath);
+      const title = titleFromMarkdown(copyPath, markdown);
+      const entry = {
+        docId,
+        path: copyPath,
+        title,
+        contentHash: contentHashForText(markdown),
+        updatedAt: now
+      };
+      await writeManifest(io, {
+        ...manifest,
+        docs: [...manifest.docs.filter((doc) => doc.path !== copyPath && doc.docId !== docId), entry],
+        updatedAt: now
+      });
     });
   }
   async function localStateForCanonical(payload) {
-    const byDocId = await getDocumentState(io, payload.docId).catch(() => void 0);
+    const byDocId = await indexedDocState(payload.docId).catch(() => void 0);
     if (byDocId) return byDocId;
-    const map = await getWorkspaceMap(io).catch(() => void 0);
+    const map = await indexedMap().catch(() => void 0);
     const byPath = map?.docs.find((doc) => doc.path === payload.path);
-    return byPath ? getDocumentState(io, byPath.docId).catch(() => void 0) : void 0;
+    return byPath ? indexedDocState(byPath.docId).catch(() => void 0) : void 0;
   }
   async function fetchCanonicalDocument2(docId) {
     try {
@@ -14330,59 +13836,65 @@ async function runBridge(options) {
     await writeBridgeStatus(root, currentBridgeStatus(state));
   }
   async function primeLocalSignatures() {
-    const map = await getWorkspaceMap(io);
+    const map = await indexedMap();
     for (const doc of map.docs) {
-      const state = await getDocumentState(io, doc.docId);
-      signatures.set(doc.docId, documentSignature(state.markdown, state.sidecar));
+      const state = await indexedDocState(doc.docId);
+      signatures.set(doc.docId, documentSignature(state.markdown));
       seenDocs.add(doc.docId);
     }
     process.stdout.write(`mdocs bridge claimed ${root} as ${rootId} at ${lastAppliedHead ?? "unknown"}
 `);
   }
   async function localSignatureFor(docId) {
-    const state = await getDocumentState(io, docId);
-    return documentSignature(state.markdown, state.sidecar);
+    const state = await indexedDocState(docId);
+    return documentSignature(state.markdown);
   }
   async function writeSourceState(head) {
-    const manifest = await indexWorkspace(io);
-    await writeManifest(io, {
-      ...manifest,
-      source: {
-        sourceId: rootId,
-        sourceName: options.sourceName ?? (basename2(root) || rootId),
-        canonicalHead: head,
-        claimedAt: manifest.source?.claimedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
-        mappings: [{ ...mapping, lastAppliedHead: head, status: head ? "synced" : "connecting", updatedAt: (/* @__PURE__ */ new Date()).toISOString() }]
-      },
-      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    await runManifest(async () => {
+      const manifest = await indexWorkspace(io, indexOptions);
+      await writeManifest(io, {
+        ...manifest,
+        source: {
+          sourceId: rootId,
+          sourceName: options.sourceName ?? (basename2(root) || rootId),
+          canonicalHead: head,
+          claimedAt: manifest.source?.claimedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+          mappings: [{ ...mapping, lastAppliedHead: head, status: head ? "synced" : "connecting", updatedAt: (/* @__PURE__ */ new Date()).toISOString() }]
+        },
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
     });
   }
   async function upsertManifestDocument(payload) {
-    const manifest = await readManifest(io).catch(() => void 0);
-    if (!manifest) return;
-    await writeManifest(io, {
-      ...manifest,
-      docs: [
-        ...manifest.docs.filter((doc) => doc.docId !== payload.docId && doc.path !== payload.path),
-        {
-          docId: payload.docId,
-          path: payload.path,
-          title: payload.sidecar.title || titleFromMarkdown(payload.path, payload.markdown),
-          contentHash: contentHashForText(payload.markdown),
-          currentSha: payload.canonicalHead ?? payload.currentSha,
-          updatedAt: payload.sidecar.updatedAt
-        }
-      ].sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0),
-      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    await runManifest(async () => {
+      const manifest = await readManifest(io).catch(() => void 0);
+      if (!manifest) return;
+      await writeManifest(io, {
+        ...manifest,
+        docs: [
+          ...manifest.docs.filter((doc) => doc.docId !== payload.docId && doc.path !== payload.path),
+          {
+            docId: payload.docId,
+            path: payload.path,
+            title: payload.title || titleFromMarkdown(payload.path, payload.markdown),
+            contentHash: contentHashForText(payload.markdown),
+            currentSha: payload.canonicalHead ?? payload.currentSha,
+            updatedAt: payload.updatedAt
+          }
+        ].sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0),
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
     });
   }
   async function removeManifestDocument(docId, path) {
-    const manifest = await readManifest(io).catch(() => void 0);
-    if (!manifest) return;
-    await writeManifest(io, {
-      ...manifest,
-      docs: manifest.docs.filter((doc) => doc.docId !== docId && doc.path !== path),
-      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    await runManifest(async () => {
+      const manifest = await readManifest(io).catch(() => void 0);
+      if (!manifest) return;
+      await writeManifest(io, {
+        ...manifest,
+        docs: manifest.docs.filter((doc) => doc.docId !== docId && doc.path !== path),
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
     });
   }
 }
@@ -14573,7 +14085,7 @@ async function fetchCanonicalDocument(options, rootId, docId) {
 function readCommitDocumentPayload(payload, workspaceId, rootId, headId) {
   if (!payload || typeof payload !== "object") return void 0;
   const value = payload;
-  if (typeof value.markdown !== "string" || !value.sidecar || typeof value.sidecar !== "object") return void 0;
+  if (typeof value.markdown !== "string") return void 0;
   return readDocumentPayload({
     workspaceId,
     rootId,
@@ -14581,7 +14093,7 @@ function readCommitDocumentPayload(payload, workspaceId, rootId, headId) {
     path: value.path,
     title: value.title,
     markdown: value.markdown,
-    sidecar: value.sidecar,
+    updatedAt: value.updatedAt,
     currentSha: headId,
     canonicalHead: headId
   });
@@ -14704,18 +14216,65 @@ function mergeReplicas(replicas, replica) {
 function rootIdForPath(path) {
   return `root_${createHash2("sha256").update(path).digest("hex").slice(0, 12)}`;
 }
-function conflictCopyPath(path) {
-  const stamp = (/* @__PURE__ */ new Date()).toISOString().replaceAll(/[:.]/g, "").slice(0, 15);
+function conflictCopyPath(path, stamp = conflictCopyStamp()) {
   return path.replace(/(\.[^./]+)?$/, (extension) => `.conflict-${stamp}${extension || ".md"}`);
 }
-function reviewFilePath(path) {
-  return path.replace(/(\.md)?$/i, ".review.md");
+async function acquireBridgeLock(root) {
+  const lockPath = join4(root, BRIDGE_LOCK_PATH);
+  await mkdir4(join4(root, ".mdocs"), { recursive: true });
+  const payload = `${JSON.stringify({ pid: process.pid, startedAt: (/* @__PURE__ */ new Date()).toISOString() }, null, 2)}
+`;
+  try {
+    await writeFile4(lockPath, payload, { flag: "wx" });
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    const holderPid = await readBridgeLockPid(lockPath);
+    if (holderPid !== void 0 && isProcessAlive(holderPid)) {
+      throw new Error(
+        `Another mdocs bridge (pid ${holderPid}) is already running for ${root}. Stop it first or remove ${lockPath} if it is stale.`
+      );
+    }
+    await writeFile4(lockPath, payload);
+  }
+  let released = false;
+  const removeSync = () => {
+    if (released) return;
+    released = true;
+    try {
+      unlinkSync(lockPath);
+    } catch {
+    }
+  };
+  process.once("exit", removeSync);
+  return {
+    release: async () => {
+      if (released) return;
+      released = true;
+      await rm3(lockPath, { force: true }).catch(() => void 0);
+    }
+  };
+}
+async function readBridgeLockPid(lockPath) {
+  try {
+    const parsed = JSON.parse(await readFile6(lockPath, "utf8"));
+    return typeof parsed.pid === "number" && Number.isInteger(parsed.pid) ? parsed.pid : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
 }
 function hashJson(value) {
   return createHash2("sha256").update(JSON.stringify(value)).digest("hex");
 }
-function documentSignature(markdown, sidecar) {
-  return hashJson({ markdown, sidecar: { ...sidecar, updatedAt: void 0 } });
+function documentSignature(markdown) {
+  return hashJson({ markdown });
 }
 async function readLocalSource(root) {
   const io = new NodeWorkspaceIO(root);
@@ -14731,12 +14290,12 @@ function readDocumentPayload(payload) {
   if (typeof value.docId !== "string") throw new Error("file-changed payload missing docId");
   if (typeof value.path !== "string") throw new Error("file-changed payload missing path");
   if (typeof value.markdown !== "string") throw new Error("file-changed payload missing markdown");
-  if (!value.sidecar || typeof value.sidecar !== "object") throw new Error("file-changed payload missing sidecar");
   return {
     docId: value.docId,
     path: value.path,
+    title: typeof value.title === "string" ? value.title : titleFromMarkdown(value.path, value.markdown),
     markdown: value.markdown,
-    sidecar: value.sidecar,
+    updatedAt: typeof value.updatedAt === "string" ? value.updatedAt : (/* @__PURE__ */ new Date()).toISOString(),
     currentSha: typeof value.currentSha === "string" ? value.currentSha : void 0,
     canonicalHead: typeof value.canonicalHead === "string" ? value.canonicalHead : void 0
   };
@@ -15036,11 +14595,7 @@ async function main() {
           ...image2.workspacePath ? { absolutePath: resolve6(cwd, image2.workspacePath) } : {}
         })),
         links: state.links,
-        ...parsed.flags["no-review"] ? {} : {
-          comments: state.sidecar.comments.filter((comment2) => comment2.status === "open"),
-          suggestions: state.sidecar.suggestions.filter((suggestion) => suggestion.status === "open"),
-          anchors: state.anchors
-        }
+        ...parsed.flags["no-review"] ? {} : { review: reviewStateForDocument(state) }
       }, parsed.flags);
       return;
     }
@@ -15050,49 +14605,25 @@ async function main() {
       return;
     }
     case "comments": {
-      const state = await getDocumentState(io, requiredArg(parsed.command[1], "path"));
-      print(state.sidecar.comments, parsed.flags);
-      return;
+      throw localReviewCommandError("comments");
     }
     case "comment": {
-      const path = requiredArg(parsed.command[1], "path");
-      const range = parseRange2(requiredFlag2(parsed.flags, "range"));
-      const body = await readRequiredTextFlag2(parsed.flags, cwd, ["body", "message"]);
-      if (!body) throw new CliError("usage_error", "Comment body is empty.", { hint: "Pass --body <text> or a non-empty --body-file." });
-      print(await addComment(io, path, range, body, actorFromFlags(parsed.flags, defaultActor())), parsed.flags);
-      return;
+      throw localReviewCommandError("comment");
     }
     case "suggestions": {
-      const state = await getDocumentState(io, requiredArg(parsed.command[1], "path"));
-      print(state.sidecar.suggestions, parsed.flags);
-      return;
+      throw localReviewCommandError("suggestions");
     }
     case "suggest": {
-      const path = requiredArg(parsed.command[1], "path");
-      const range = parseRange2(requiredFlag2(parsed.flags, "range"));
-      const replacement = await readRequiredTextFlag2(parsed.flags, cwd, ["with", "replacement"]);
-      const message = await readOptionalTextFlag2(parsed.flags, cwd, ["message"]) ?? "Suggested edit";
-      print(await addSuggestion(io, path, range, replacement, message, actorFromFlags(parsed.flags, {
-        id: "agent_local",
-        kind: "agent",
-        name: "Local Agent"
-      })), parsed.flags);
-      return;
+      throw localReviewCommandError("suggest");
     }
     case "accept": {
-      const suggestionId = requiredArg(parsed.command[1], "suggestionId");
-      print(await acceptSuggestion(io, suggestionId, actorFromFlags(parsed.flags, defaultActor())), parsed.flags);
-      return;
+      throw localReviewCommandError("accept");
     }
     case "reject": {
-      const suggestionId = requiredArg(parsed.command[1], "suggestionId");
-      print(await rejectSuggestion(io, suggestionId, actorFromFlags(parsed.flags, defaultActor())), parsed.flags);
-      return;
+      throw localReviewCommandError("reject");
     }
     case "resolve-comment": {
-      const commentId = requiredArg(parsed.command[1], "commentId");
-      print(await resolveComment(io, commentId, actorFromFlags(parsed.flags, defaultActor())), parsed.flags);
-      return;
+      throw localReviewCommandError("resolve-comment");
     }
     case "sync":
     case "status": {
@@ -15149,7 +14680,7 @@ async function main() {
         claimToken: typeof parsed.flags.claim === "string" ? parsed.flags.claim : void 0,
         actorId: typeof parsed.flags.actor === "string" ? parsed.flags.actor : void 0,
         actorName: typeof parsed.flags["actor-name"] === "string" ? parsed.flags["actor-name"] : void 0,
-        intervalMs: Number(parsed.flags.interval ?? 1e3),
+        intervalMs: validateBridgeIntervalMs(parsed.flags.interval),
         token: typeof parsed.flags.token === "string" ? parsed.flags.token : process.env.MDOCS_BRIDGE_TOKEN || void 0,
         requestToken: Boolean(parsed.flags["request-token"] || parsed.flags.pair),
         pairingTimeoutMs: typeof parsed.flags["pairing-timeout-ms"] === "string" ? Number(parsed.flags["pairing-timeout-ms"]) : void 0,
@@ -15176,9 +14707,15 @@ async function main() {
         });
         return;
       }
+      const workspaceId = typeof parsed.flags.workspace === "string" && parsed.flags.workspace.trim() ? parsed.flags.workspace.trim() : void 0;
+      if (!workspaceId) {
+        throw new CliError("usage_error", "Missing --workspace <id> for mdocs bridge.", {
+          hint: "Pass the workspace explicitly, for example --workspace ws_123. The bridge no longer assumes a demo workspace."
+        });
+      }
       const options = {
         ...baseOptions,
-        workspaceId: typeof parsed.flags.workspace === "string" ? parsed.flags.workspace : "workspace_demo",
+        workspaceId,
         baseUrl: bridgeBaseUrl(parsed.flags)
       };
       if (subcommand === "setup") await runBridgeSetup(options);
@@ -15264,23 +14801,14 @@ function parseArgs(args) {
   }
   return { command, flags };
 }
-function parseRange2(value) {
-  const [start, end = start] = value.split(":").map(Number);
-  if (!Number.isInteger(start) || !Number.isInteger(end) || !start || !end || start < 1 || end < start) {
-    throw new CliError("invalid_range", `Invalid --range value "${value}".`, {
-      hint: "Use --range <startLine>:<endLine> with 1-based inclusive line numbers, for example --range 4:9."
-    });
-  }
-  return { startLine: start, endLine: end };
-}
 function requiredArg(value, name) {
   if (!value) throw new CliError("usage_error", `Missing <${name}> argument.`);
   return value;
 }
-function requiredFlag2(flags, name) {
-  const value = flags[name];
-  if (typeof value !== "string") throw new CliError("usage_error", `Missing --${name}.`);
-  return value;
+function localReviewCommandError(command) {
+  return new CliError("usage_error", `Local review command "${command}" was removed.`, {
+    hint: "Use `mdocs remote ...` or the remote MCP connector so comments, suggestions, accept, and reject go through DocumentAuthority."
+  });
 }
 function bridgeBaseUrl(flags) {
   const configured = optionalBridgeBaseUrl(flags);
@@ -15294,40 +14822,6 @@ function optionalBridgeBaseUrl(flags) {
   const configured = process.env.MDOCS_BASE_URL?.trim();
   return configured || void 0;
 }
-async function readRequiredTextFlag2(flags, cwd, names) {
-  const value = await readOptionalTextFlag2(flags, cwd, names);
-  if (value === void 0) {
-    throw new CliError("usage_error", `Pass --${names[0]} <text> or --${names[0]}-file <path>.`, {
-      hint: `For multiline text, write it to a file and pass --${names[0]}-file.`
-    });
-  }
-  return value;
-}
-async function readOptionalTextFlag2(flags, cwd, names) {
-  for (const name of names) {
-    const fileValue = flags[`${name}-file`];
-    if (typeof fileValue === "string") return readFile8(resolve6(cwd, fileValue), "utf8");
-    const value = flags[name];
-    if (typeof value === "string") return value;
-  }
-  return void 0;
-}
-function actorFromFlags(flags, fallback) {
-  const id = typeof flags.actor === "string" ? flags.actor : fallback.id;
-  const name = typeof flags["actor-name"] === "string" ? flags["actor-name"] : fallback.name;
-  const email = typeof flags["actor-email"] === "string" ? flags["actor-email"] : fallback.email;
-  const kind = actorKindFromFlag(flags["actor-kind"]) ?? fallback.kind;
-  return {
-    id,
-    kind,
-    name,
-    ...email ? { email } : {}
-  };
-}
-function actorKindFromFlag(value) {
-  if (value === "human" || value === "agent" || value === "system") return value;
-  return void 0;
-}
 function print(value, flags) {
   if (flags.json || typeof value !== "string") {
     process.stdout.write(`${JSON.stringify(value, null, 2)}
@@ -15347,20 +14841,14 @@ Commands:
   init [path]                         Initialize .mdocs and index Markdown files
   map --json                          Print workspace map
   graph --json                        Print workspace knowledge graph nodes and edges
-  state <path> --json                 Print merged Markdown and sidecar state
+  state <path> --json                 Print clean Markdown document state
   context <path> --json               Print agent-ready context
   context <path> --summary --json     Print document metadata and headings
-  review <path> --json                Print open comments, suggestions, anchors
-  comments <path> --json              List comments
-  comment <path> --range 3:5 --body   Add a sidecar comment
-  suggestions <path> --json           List suggestions
-  suggest <path> --range 3:5 --with   Add a reviewMarkdown suggestion
-  suggest <path> --range 3:5 --with-file replacement.md
-                                      Add a multiline reviewMarkdown suggestion
-  accept <suggestionId>               Apply and accept a suggestion
-  reject <suggestionId>               Reject a suggestion
-  resolve-comment <commentId>         Resolve a comment thread
-  status --json                       Print Git status and sidecar map
+  review <path> --json                Print local authority-review redirect metadata
+  comments|comment|suggestions        Removed locally; use remote authority commands
+  suggest|accept|reject|resolve-comment
+                                      Removed locally; use remote authority commands
+  status --json                       Print Git status and workspace map
   sync --json                         Alias for status until hosted sync is configured
   diff [path]                         Print local Git diff
   history [path] --json               Print local Git history
@@ -15393,7 +14881,7 @@ Commands:
                                       (or set MDOCS_BRIDGE_TOKEN)
   bridge --claim <token> --root . --canonical-prefix prompts --replica-prefix packages/agent/prompts
                                       Claim an existing repo path as a Magic-canonical source mapping
-  doctor --json                       Validate sidecar mappings
+  doctor --json                       Validate workspace map and agent readiness
   serve-mcp                           Start JSON-RPC MCP-compatible stdio server
   version [--json]                    Print CLI version
   help <command>                      Show usage, examples, and notes for one command